@kaynooo/env-tools 0.4.1 → 0.6.0

package/dist/ev.js

@@ -343,6 +343,26 @@ function printJson(value) {
   console.log(JSON.stringify(value, undefined, 2));
 }
 
+// ../kit/src/text.ts
+var ANSI = new RegExp(`${String.fromCharCode(27)}\\[[\\d;?]*[a-z]`, "gi");
+function distance(a, b) {
+  let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (const [i, left] of [...a].entries()) {
+    const current = [i + 1];
+    for (const [j, right] of [...b].entries())
+      current.push(Math.min((previous[j + 1] ?? 0) + 1, (current[j] ?? 0) + 1, (previous[j] ?? 0) + (left === right ? 0 : 1)));
+    previous = current;
+  }
+  return previous[b.length] ?? 0;
+}
+function closest(name, names) {
+  const started = names.find((known) => known.startsWith(name));
+  if (started !== undefined)
+    return started;
+  const [best] = names.map((known) => ({ known, far: distance(name, known) })).sort((a, b) => a.far - b.far);
+  return best !== undefined && best.far <= (name.length < 4 ? 1 : 2) ? best.known : undefined;
+}
+
 // ../kit/src/args.ts
 function jsonOption(holds) {
   return { type: "boolean", description: holds === undefined ? "print JSON" : `print JSON: ${holds}` };
@@ -362,8 +382,8 @@ function fail(message, code = 2, hint) {
 }
 
 class UsageError extends Exit {
-  constructor(message) {
-    super(message, 2);
+  constructor(message, hint) {
+    super(message, 2, hint);
   }
 }
 function badUsage(message) {
@@ -385,24 +405,70 @@ class Completing {
 var completion = { active: false };
 var OPTIONAL = /\[[^\]]+\]/g;
 var USAGE_PREFIX = /^usage:\s*/i;
+var FULL_STOP = /\.$/;
+var DASHES = /^-+/;
 function usageLine(usage, colors = paint(process4.stdout)) {
   return `${colors.bold("Usage:")} ${usage.replace(USAGE_PREFIX, "").replaceAll(OPTIONAL, (part) => colors.dim(part))}`;
 }
-function helpText(usage, options, colors = paint(process4.stdout)) {
-  return [usageLine(usage, colors), "", colors.bold("Options:"), ...optionRows(options, colors)].join(`
+function helpText(usage, options, colors = paint(process4.stdout), { examples = [], replaces } = {}) {
+  return [usageLine(usage, colors), ...replacesRows(replaces, colors), "", colors.bold("Options:"), ...optionRows(options, colors), ...exampleRows(examples, colors)].join(`
 `);
 }
+function replacesRows(replaces, colors = paint(process4.stdout)) {
+  return replaces === undefined ? [] : ["", `${colors.bold("Instead of:")} ${replaces}`];
+}
+function wantsHelpJson(env = process4.env) {
+  return env.KIT_HELP === "json";
+}
+function description(usage, { examples = [], replaces } = {}) {
+  const lines = usage.replace(USAGE_PREFIX, "").split(`
+`);
+  const first = lines[0];
+  const colon = first.indexOf(": ");
+  const prose = lines[lines.indexOf("") + 1] ?? "";
+  const fallback = lines.includes("") ? `${prose.charAt(0).toLowerCase()}${prose.slice(1)}`.replace(FULL_STOP, "") : "";
+  return {
+    synopsis: colon === -1 ? first : first.slice(0, colon),
+    summary: colon === -1 ? fallback : first.slice(colon + 2),
+    ...replaces === undefined ? {} : { replaces },
+    examples: examples.map((example) => typeof example === "string" ? { line: example } : { line: example[0], note: example[1] })
+  };
+}
+function exampleRows(examples, colors = paint(process4.stdout)) {
+  if (examples.length === 0)
+    return [];
+  return ["", colors.bold("Examples:"), ...examples.map((example) => typeof example === "string" ? `  ${example}` : `  ${example[0]}  ${colors.dim(`# ${example[1]}`)}`)];
+}
 function optionRows(options, colors = paint(process4.stdout)) {
   const rows = Object.entries(options).map(([name, option]) => {
     const short = option.short === undefined ? "    " : `${colors.cyan(`-${option.short}`)}, `;
     const value = option.type === "string" ? ` ${colors.dim("<value>")}` : "";
-    return { flag: `${short}${colors.cyan(`--${name}`)}${value}`, width: `-x, --${name}`.length + (option.type === "string" ? " <value>".length : 0), description: option.description };
+    return { flag: `${short}${colors.cyan(`--${name}`)}${value}`, width: `-x, --${name}`.length + (option.type === "string" ? " <value>".length : 0), description: option.description ?? "" };
   });
   const width = Math.max(0, ...rows.map((row) => row.width));
-  return rows.map((row) => `  ${row.flag}${" ".repeat(width - row.width)}  ${colors.dim(row.description)}`);
+  return rows.map((row) => row.description === "" ? `  ${row.flag}` : `  ${row.flag}${" ".repeat(width - row.width)}  ${colors.dim(row.description)}`);
+}
+var OUTPUT_OPTIONS = {
+  color: { type: "string", description: "auto (on a terminal alone), always or never" },
+  plain: { type: "boolean", description: "plain text, no colour or spinner: --color never" }
+};
+function applyOutput(color, plain, env = process4.env) {
+  const when = plain === true ? "never" : color ?? "auto";
+  if (when === "auto")
+    return;
+  if (when !== "always" && when !== "never")
+    badUsage(`--color takes auto, always or never, not ${when}`);
+  if (when === "always") {
+    env.FORCE_COLOR = "1";
+    delete env.NO_COLOR;
+  } else {
+    env.NO_COLOR = "1";
+    delete env.FORCE_COLOR;
+  }
 }
 function parse(args, usage, options, settings = {}) {
-  const all = { ...options, help: { type: "boolean", short: "h", description: "show this help" } };
+  const output = Object.fromEntries(Object.entries(OUTPUT_OPTIONS).filter(([name]) => !(name in options)));
+  const all = { ...options, ...output, help: { type: "boolean", short: "h", description: "show this help" } };
   if (completion.active)
     throw new Completing(all);
   const separator = settings.rest === true ? args.indexOf("--") : -1;
@@ -410,12 +476,15 @@ function parse(args, usage, options, settings = {}) {
   const rest = separator === -1 ? undefined : args.slice(separator + 1);
   let parsed;
   try {
-    parsed = parseArgs({ args: own, options: all, allowPositionals: true, allowNegative: settings.allowNegative === true, strict: true });
+    parsed = parseArgs({ args: joinDashValues(own, all), options: all, allowPositionals: true, allowNegative: settings.allowNegative === true, strict: true });
   } catch (error) {
-    badUsage(parseError(error));
+    const message = parseError(error);
+    throw new UsageError(message, nearestOption(message, all, settings.allowNegative === true));
   }
-  if (parsed.values.help === true) {
-    console.log(helpText(usage, all));
+  const values = parsed.values;
+  applyOutput("color" in output ? values.color : undefined, "plain" in output ? values.plain : undefined);
+  if (values.help === true) {
+    console.log(wantsHelpJson() ? JSON.stringify(description(usage, settings)) : helpText(usage, all, undefined, settings));
     throw new HelpShown;
   }
   if (settings.positionals !== undefined)
@@ -430,10 +499,45 @@ function checkPositionals(given, names) {
   if (!variadic && given.length > names.length)
     badUsage(`unexpected argument ${given[names.length]}`);
 }
+function joinDashValues(args, options) {
+  const longOf = new Map(Object.entries(options).flatMap(([name, option]) => option.short === undefined ? [[`--${name}`, name]] : [[`--${name}`, name], [`-${option.short}`, name]]));
+  const isOption = (arg) => arg === "--" || longOf.has(arg.includes("=") ? arg.slice(0, arg.indexOf("=")) : arg);
+  const joined = [];
+  for (let i = 0;i < args.length; i++) {
+    const arg = args[i] ?? "";
+    if (arg === "--")
+      return [...joined, ...args.slice(i)];
+    const name = longOf.get(arg);
+    const next = args[i + 1];
+    if (name !== undefined && options[name]?.type === "string" && next !== undefined && next.startsWith("-") && next !== "-" && !isOption(next)) {
+      joined.push(`--${name}=${next}`);
+      i++;
+    } else {
+      joined.push(arg);
+    }
+  }
+  return joined;
+}
 function parseError(error) {
   const message = upTo(error instanceof Error ? error.message : String(error), ". ");
   return `${message.charAt(0).toLowerCase()}${message.slice(1)}`;
 }
+var UNKNOWN_OPTION = /^unknown option '(-[^']+)'/;
+function nearestOption(message, options, allowNegative) {
+  const typed = UNKNOWN_OPTION.exec(message)?.[1];
+  if (typed === undefined)
+    return;
+  const word = typed.replace(DASHES, "");
+  if (word.length < 2 && !typed.startsWith("--"))
+    return;
+  const known = Object.entries(options).flatMap(([name, option]) => [
+    ...option.short === undefined ? [] : [`-${option.short}`],
+    `--${name}`,
+    ...allowNegative && option.type === "boolean" ? [`--no-${name}`] : []
+  ]);
+  const meant = closest(word, known.map((flag) => flag.replace(DASHES, "")));
+  return meant === undefined ? undefined : `did you mean ${known.find((flag) => flag.replace(DASHES, "") === meant)}?`;
+}
 async function readInput(path, { noStdin = "nothing is piped on stdin" } = {}) {
   if (path === "-") {
     if (process4.stdin.isTTY)
@@ -447,42 +551,75 @@ async function readInput(path, { noStdin = "nothing is piped on stdin" } = {}) {
 }
 // ../kit/src/cli.ts
 import process5 from "process";
-
-// ../kit/src/text.ts
-var ANSI = new RegExp(`${String.fromCharCode(27)}\\[[\\d;?]*[a-z]`, "gi");
-function distance(a, b) {
-  let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
-  for (const [i, left] of [...a].entries()) {
-    const current = [i + 1];
-    for (const [j, right] of [...b].entries())
-      current.push(Math.min((previous[j + 1] ?? 0) + 1, (current[j] ?? 0) + 1, (previous[j] ?? 0) + (left === right ? 0 : 1)));
-    previous = current;
+var LEVEL_OPTIONS = {
+  ...OUTPUT_OPTIONS,
+  help: { type: "boolean", short: "h", description: "show this help" }
+};
+var TOP_OPTIONS = { ...LEVEL_OPTIONS, version: { type: "boolean", short: "v", description: "print the version" } };
+async function commandRows(commands, colors) {
+  const width = Math.max(...Object.keys(commands).map((name) => name.length));
+  const groups = new Map([["Commands:", []]]);
+  const summaries = await Promise.all(Object.values(commands).map(async ({ summary }) => resolveSummary(summary)));
+  for (const [index, [name, { group }]] of Object.entries(commands).entries()) {
+    const heading = group === undefined ? "Commands:" : `${group}:`;
+    const rows = groups.get(heading) ?? [];
+    rows.push(`  ${colors.cyan(name.padEnd(width))}  ${colors.dim(summaries[index])}`);
+    groups.set(heading, rows);
+  }
+  return [...groups].filter(([, rows]) => rows.length > 0).flatMap(([heading, rows], index) => [...index === 0 ? [] : [""], colors.bold(heading), ...rows]);
+}
+function takeOutputFlags(argv) {
+  let index = 0;
+  for (;index < argv.length; index++) {
+    const word = argv[index];
+    if (word === "--plain")
+      applyOutput(undefined, true);
+    else if (word.startsWith("--color="))
+      applyOutput(word.slice("--color=".length), undefined);
+    else if (word === "--color" && argv[index + 1] !== undefined)
+      applyOutput(argv[++index], undefined);
+    else
+      break;
   }
-  return previous[b.length] ?? 0;
+  return argv.slice(index);
 }
-
-// ../kit/src/cli.ts
-function closest(name, names) {
-  const started = names.find((known) => known.startsWith(name));
-  if (started !== undefined)
-    return started;
-  const [best] = names.map((known) => ({ known, far: distance(name, known) })).sort((a, b) => a.far - b.far);
-  return best !== undefined && best.far <= (name.length < 4 ? 1 : 2) ? best.known : undefined;
+async function resolveSummary(summary) {
+  return typeof summary === "string" ? summary : summary();
+}
+function scopeOf(commands, extra, aliases) {
+  return { commands: typeof commands === "function" ? {} : commands, lazy: [...typeof commands === "function" ? [commands] : [], ...extra === undefined ? [] : [extra]], aliases };
 }
-async function help({ path, header, commands, defaultCommand }, stream) {
+async function expand(scope, words) {
+  if (scope.lazy.length === 0)
+    return scope;
+  const commands = { ...scope.commands };
+  for (const added of await Promise.all(scope.lazy.map(async (lazy) => lazy(words)))) {
+    for (const [name, command] of Object.entries(added))
+      commands[name] ??= command;
+  }
+  return { ...scope, commands, lazy: [] };
+}
+async function help({ path, header, summary: lazySummary, commands, defaultCommand, examples, replaces }, stream) {
   const colors = paint(stream);
-  const width = Math.max(...Object.keys(commands).map((name) => name.length));
   const prefix = path.join(" ");
+  const summary = await resolveSummary(lazySummary);
+  if (wantsHelpJson())
+    return JSON.stringify(description(`${prefix} <command> [options]: ${summary}`, { examples, replaces }));
   const fallback = defaultCommand === undefined ? undefined : commands[defaultCommand];
   const options = fallback !== undefined && "run" in fallback ? await optionsOf(fallback.run) : undefined;
+  const own = Object.entries(options ?? {}).filter(([name]) => !(name in TOP_OPTIONS));
   return [
-    header(colors),
+    header(colors, summary),
     "",
     usageLine(`${prefix} ${defaultCommand === undefined ? colors.cyan("<command>") : `[${colors.cyan("<command>")}]`} [options]`, colors),
+    ...replacesRows(replaces, colors),
+    "",
+    ...await commandRows(commands, colors),
+    ...own.length === 0 ? [] : ["", `${colors.bold(`Options of ${defaultCommand}:`)} ${colors.dim("the command run when none is named")}`, ...optionRows(Object.fromEntries(own), colors)],
     "",
-    colors.bold("Commands:"),
-    ...Object.entries(commands).map(([name, { summary }]) => `  ${colors.cyan(name.padEnd(width))}  ${colors.dim(summary)}`),
-    ...options === undefined || Object.keys(options).length === 0 ? [] : ["", `${colors.bold(`Options of ${defaultCommand}:`)} ${colors.dim("the command run when none is named")}`, ...optionRows(options, colors)],
+    colors.bold("Options:"),
+    ...optionRows(path.length === 1 ? TOP_OPTIONS : LEVEL_OPTIONS, colors),
+    ...exampleRows(examples ?? [], colors),
     "",
     `${colors.dim("Run")} ${prefix} ${colors.cyan("<command>")} --help ${colors.dim("for its options.")}`
   ].join(`
@@ -496,24 +633,38 @@ function printError(prefix, message, hint, cause) {
   ${styled ? tint(label) : `${label}:`} ${text}`;
   console.error(`${head} ${message}${under("cause", cause, colors.dim)}${under("hint", hint, colors.yellow)}`);
 }
-function reportThrown(prefix, error, redact = (text) => text) {
+function printJsonError(message, hint, cause) {
+  console.error(JSON.stringify({ error: message, ...hint === undefined ? {} : { hint }, ...cause === undefined ? {} : { cause } }));
+}
+function wantsJson(argv) {
+  const end = argv.indexOf("--");
+  return (end === -1 ? argv : argv.slice(0, end)).includes("--json");
+}
+function reportThrown(prefix, error, redact = (text) => text, json = false) {
   if (error instanceof HelpShown)
     return 0;
   const help = error instanceof UsageError ? `run ${prefix} --help for its options` : undefined;
   const named = error instanceof Error && !(error instanceof Exit) && error.name !== "Error" ? `${error.name}: ${error.message}` : undefined;
   const cause = error instanceof Error && error.cause instanceof Error ? redact(error.cause.message) : undefined;
-  printError(prefix, redact(named ?? (error instanceof Error ? error.message : String(error))), error instanceof Exit ? error.hint ?? help : undefined, cause);
+  const report = json ? printJsonError : (message, hint, causeText) => printError(prefix, message, hint, causeText);
+  report(redact(named ?? (error instanceof Error ? error.message : String(error))), error instanceof Exit ? error.hint ?? help : undefined, cause);
   return error instanceof Exit ? error.code : 1;
 }
-async function dispatch(level, argv, { version, redact }) {
-  const [name, ...args] = argv;
+async function dispatch(level, typed, { version, redact }) {
   const prefix = level.path.join(" ");
+  let argv;
+  try {
+    argv = takeOutputFlags(typed);
+  } catch (error) {
+    return reportThrown(prefix, error);
+  }
+  const [name, ...args] = argv;
   if (name === undefined && level.path.length > 1) {
-    console.error(await help(level, process5.stderr));
+    console.error(await help(await expand(level, [...level.path.slice(1), ...argv]), process5.stderr));
     return 2;
   }
   if (name === undefined || name === "help" || name === "--help" || name === "-h") {
-    console.log(await help(level, process5.stdout));
+    console.log(await help(await expand(level, [...level.path.slice(1), ...argv]), process5.stdout));
     return 0;
   }
   if (level.path.length === 1 && (name === "--version" || name === "-v")) {
@@ -522,6 +673,10 @@ async function dispatch(level, argv, { version, redact }) {
   }
   let command = level.commands[level.aliases?.[name] ?? name];
   let rest = args;
+  if (command === undefined && level.lazy.length > 0) {
+    level = await expand(level, [...level.path.slice(1), ...argv]);
+    command = level.commands[level.aliases?.[name] ?? name];
+  }
   if (command === undefined && level.defaultCommand !== undefined) {
     command = level.commands[level.defaultCommand];
     rest = argv;
@@ -533,12 +688,12 @@ async function dispatch(level, argv, { version, redact }) {
   }
   if ("commands" in command) {
     const { summary } = command;
-    return dispatch({ path: [...level.path, name], header: (colors) => `${colors.bold(`${prefix} ${name}`)}  ${summary}`, commands: command.commands, aliases: command.aliases, defaultCommand: undefined }, rest, { version, redact });
+    return dispatch({ path: [...level.path, name], header: (colors, text) => `${colors.bold(`${prefix} ${name}`)}  ${text}`, summary, ...scopeOf(command.commands, command.extraCommands, command.aliases), defaultCommand: undefined, examples: command.examples, replaces: undefined }, rest, { version, redact });
   }
   try {
     return await command.run(rest);
   } catch (error) {
-    return reportThrown(`${prefix} ${name}`, error, redact);
+    return reportThrown(`${prefix} ${name}`, error, redact, wantsJson(rest));
   }
 }
 var COMPLETE = "__complete";
@@ -558,18 +713,24 @@ async function optionsOf(run) {
 async function leafCandidates(run, words) {
   if (!(words.at(-1) ?? "").startsWith("-"))
     return [FILES];
-  return Object.entries(await optionsOf(run)).map(([name, option]) => `--${name}	${option.description}`);
+  return Object.entries(await optionsOf(run)).map(([name, option]) => option.description === undefined ? `--${name}` : `--${name}	${option.description}`);
 }
-async function candidates(commands, aliases, defaultCommand, words) {
+async function candidates(scope, defaultCommand, words, before = []) {
   const [word = "", ...rest] = words;
-  const command = commands[aliases?.[word] ?? word];
-  if (rest.length === 0 && !word.startsWith("-"))
-    return Object.entries(commands).map(([name, { summary }]) => `${name}	${summary}`);
+  const listing = rest.length === 0 && !word.startsWith("-");
+  let { commands, aliases } = scope;
+  let command = commands[aliases?.[word] ?? word];
+  if (listing || command === undefined) {
+    ({ commands, aliases } = await expand(scope, [...before, ...words]));
+    command = commands[aliases?.[word] ?? word];
+  }
+  if (listing)
+    return Promise.all(Object.entries(commands).map(async ([name, { summary }]) => `${name}	${await resolveSummary(summary)}`));
   if (command === undefined) {
     const fallback = defaultCommand === undefined ? undefined : commands[defaultCommand];
     return fallback !== undefined && "run" in fallback ? leafCandidates(fallback.run, words) : [];
   }
-  return "commands" in command ? candidates(command.commands, command.aliases, undefined, rest) : leafCandidates(command.run, rest);
+  return "commands" in command ? candidates(scopeOf(command.commands, command.extraCommands, command.aliases), undefined, rest, [...before, word]) : leafCandidates(command.run, rest);
 }
 async function printCandidates(found) {
   for (const line of await found)
@@ -578,8 +739,8 @@ async function printCandidates(found) {
 }
 async function runCli(cli, argv = process5.argv.slice(2)) {
   if (argv[0] === COMPLETE)
-    return printCandidates(candidates(cli.commands, cli.aliases, cli.defaultCommand, argv.slice(1)));
-  return dispatch({ path: [cli.name], header: (colors) => `${colors.bold(cli.name)} ${colors.dim(cli.version)}  ${cli.about}`, commands: cli.commands, aliases: cli.aliases, defaultCommand: cli.defaultCommand }, argv, { version: cli.version, redact: cli.redact });
+    return printCandidates(candidates(scopeOf(cli.commands, cli.extraCommands, cli.aliases), cli.defaultCommand, argv.slice(1)));
+  return dispatch({ path: [cli.name], header: (colors, about) => `${colors.bold(cli.name)} ${colors.dim(cli.version)}  ${about}`, summary: cli.about, ...scopeOf(cli.commands, cli.extraCommands, cli.aliases), defaultCommand: cli.defaultCommand, examples: cli.examples, replaces: cli.replaces }, argv, { version: cli.version, redact: cli.redact });
 }
 async function runMain({ name, version, run, redact }, argv = process5.argv.slice(2)) {
   if (argv[0] === COMPLETE)
@@ -591,24 +752,25 @@ async function runMain({ name, version, run, redact }, argv = process5.argv.slic
   try {
     return await run(argv);
   } catch (error) {
-    return reportThrown(name, error, redact);
+    return reportThrown(name, error, redact, wantsJson(argv));
   }
 }
 // package.json
-var version = "0.4.1";
+var version = "0.6.0";
 
 // src/commands/audit.ts
-import { stat as stat3 } from "fs/promises";
+import { stat as stat4 } from "fs/promises";
 import { relative, resolve } from "path";
 import process7 from "process";
 
 // src/audit.ts
-import { readdir as readdir2, stat } from "fs/promises";
-import { dirname, join } from "path";
+import { readdir as readdir2, stat as stat2 } from "fs/promises";
+import { dirname as dirname2, join as join2 } from "path";
 var {$ } = globalThis.Bun;
 
 // src/files.ts
-import { readdir } from "fs/promises";
+import { chmod, readdir, realpath, rename, rm, stat, writeFile } from "fs/promises";
+import { basename, dirname, join } from "path";
 
 // src/dotenv.ts
 var ASSIGNMENT = /^\s*(?:export\s+)?([A-Z_][\w.-]*)\s*=(.*)$/i;
@@ -731,6 +893,17 @@ var TOKEN_FORMATS = [
   ["Slack token", /\bxox[abprs]-[\w-]{10,}/g],
   ["JWT", /\beyJ[\w-]+\.[\w-]+\.[\w-]+/g]
 ];
+var URL_PARTS = /\b[a-z][a-z0-9+.-]*:\/\/([^\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],
+  ["Slack webhook", /^hooks\.slack\.com\/(?:services|workflows)\/(?:[\w-]+\/)*([\w-]+)/di],
+  ["Uptime Kuma push URL", /\/api\/push\/([\w-]+)/di],
+  ["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) {
@@ -754,6 +927,39 @@ function knownSecrets(pairs) {
 function urlPasswords(text) {
   return [...text.matchAll(URL_PASSWORD)].flatMap((url) => url[1] ?? []);
 }
+function urlTokens(line) {
+  const found = [];
+  const add = (kind, start, value) => {
+    found.push({ start, end: start + value.length, kind, mask: hint(value) });
+  };
+  for (const url of line.matchAll(URL_PARTS)) {
+    const [authority, path = "", query] = [url[1] ?? "", url[2] ?? "", url[3]];
+    const authorityStart = url.indices?.[1]?.[0];
+    const pathStart = url.indices?.[2]?.[0];
+    const queryStart = url.indices?.[3]?.[0];
+    if (authorityStart === undefined || pathStart === undefined)
+      continue;
+    const hostAt = authority.lastIndexOf("@") + 1;
+    const target = authority.slice(hostAt) + path;
+    for (const [kind, pattern] of WEBHOOK_FORMATS) {
+      const [start, end] = pattern.exec(target)?.indices?.[1] ?? [];
+      if (start !== undefined && end !== undefined)
+        add(kind, authorityStart + hostAt + start, target.slice(start, end));
+    }
+    for (const segment of path.matchAll(PATH_SEGMENT)) {
+      if (OPAQUE_SEGMENT.test(segment[0]))
+        add("URL token", pathStart + segment.index, segment[0]);
+    }
+    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);
+    }
+  }
+  return found.filter((match) => match.end > match.start);
+}
 function findSecrets(line, known) {
   const found = [];
   for (const url of line.matchAll(URL_PASSWORD)) {
@@ -765,6 +971,7 @@ function findSecrets(line, known) {
     for (const token of line.matchAll(pattern))
       found.push({ start: token.index, end: token.index + token[0].length, kind, mask: hint(token[0]) });
   }
+  found.push(...urlTokens(line));
   if (known?.pattern !== undefined) {
     for (const value of line.matchAll(known.pattern))
       found.push({ start: value.index, end: value.index + value[0].length, kind: `value of ${known.keys.get(value[0])}`, mask: hint(value[0]) });
@@ -806,7 +1013,20 @@ async function readEnv(path) {
   return parseDotenv(await file.text());
 }
 async function writeEnv(path, file) {
-  await Bun.write(path, serializeDotenv(file));
+  let target = path;
+  let mode = 384;
+  try {
+    target = await realpath(path);
+    mode = (await stat(target)).mode & 511;
+  } catch {}
+  const temp = join(dirname(target), `.${basename(target)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+  try {
+    await writeFile(temp, serializeDotenv(file), { mode: 384, flag: "wx" });
+    await chmod(temp, mode);
+    await rename(temp, target);
+  } finally {
+    await rm(temp, { force: true });
+  }
 }
 async function loadKnown(folder = process.cwd()) {
   const pairs = [];
@@ -842,16 +1062,16 @@ function inlineSecrets(compose) {
   return [...new Set(names)];
 }
 async function openToOthers(path) {
-  if (((await stat(path)).mode & 4) === 0)
+  if (((await stat2(path)).mode & 4) === 0)
     return false;
-  for (let dir = dirname(path);dir !== "/"; dir = dirname(dir)) {
-    if (((await stat(dir)).mode & 1) === 0)
+  for (let dir = dirname2(path);dir !== "/"; dir = dirname2(dir)) {
+    if (((await stat2(dir)).mode & 1) === 0)
       return false;
   }
   return true;
 }
 async function tracked(path) {
-  return (await $`git ls-files --error-unmatch -- ${path}`.cwd(dirname(path)).quiet().nothrow()).exitCode === 0;
+  return (await $`git ls-files --error-unmatch -- ${path}`.cwd(dirname2(path)).quiet().nothrow()).exitCode === 0;
 }
 async function* candidates2(root, unread, depth = 0) {
   let found;
@@ -862,7 +1082,7 @@ async function* candidates2(root, unread, depth = 0) {
     return;
   }
   for (const entry of found) {
-    const path = join(root, entry.name);
+    const path = join2(root, entry.name);
     if (entry.isDirectory() && depth < MAX_DEPTH && !SKIPPED.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)))
@@ -891,8 +1111,8 @@ async function audit(roots) {
 }
 
 // src/fix.ts
-import { chmod, chown, rm, stat as stat2, writeFile } from "fs/promises";
-import { dirname as dirname2, join as join2 } from "path";
+import { chmod as chmod2, chown, rm as rm2, stat as stat3, writeFile as writeFile2 } 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_]+)=(.*)$/;
 var TRAILING = /^\s*(?:#.*)?$/;
@@ -954,7 +1174,7 @@ function envLine(key, value) {
 `) ? undefined : `${key}='${value}'`;
 }
 async function resolved(path) {
-  const run = Bun.spawn(["docker", "compose", "-f", path, "config", "--format", "json"], { cwd: dirname2(path), stdout: "pipe", stderr: "ignore", stdin: "ignore" });
+  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]);
   return code === 0 ? out : undefined;
 }
@@ -965,7 +1185,7 @@ function gainedBy(before, after, key) {
 }
 async function shutOthersOut(path) {
   try {
-    await chmod(path, (await stat2(path)).mode & 504);
+    await chmod2(path, (await stat3(path)).mode & 504);
     return true;
   } catch (error) {
     if (error.code === "EPERM")
@@ -974,7 +1194,7 @@ async function shutOthersOut(path) {
   }
 }
 async function fixCompose(path) {
-  const env = join2(dirname2(path), ".env");
+  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 ?? "");
@@ -1026,15 +1246,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 writeFile(env, envAfter, { mode: 384 });
-    const { uid, gid } = await stat2(path);
+    await writeFile2(env, envAfter, { mode: 384 });
+    const { uid, gid } = await stat3(path);
     try {
       await chown(env, uid, gid);
     } catch {}
   } else {
-    await writeFile(env, envAfter);
+    await writeFile2(env, envAfter);
   }
-  await writeFile(path, composeAfter);
+  await writeFile2(path, composeAfter);
   if (!docker) {
     fix.check = "no docker";
     return;
@@ -1048,11 +1268,11 @@ async function move(fix, compose, composeAfter, envBefore, envAfter) {
     fix.check = "same";
     return;
   }
-  await writeFile(path, compose);
+  await writeFile2(path, compose);
   if (envBefore === undefined)
-    await rm(env);
+    await rm2(env);
   else
-    await writeFile(env, envBefore);
+    await writeFile2(env, envBefore);
   fix.check = "rolled back";
   fix.left.push(...fix.moved.map((key) => {
     const gained = after === undefined ? [] : gainedBy(before, after, key);
@@ -1067,7 +1287,7 @@ var usage = `ev audit [dir...] [--fix]
 Lists the .env files any account on the machine can read or git tracks, and the compose files any account can read that write a secret out (a secret-named value or a URL password) instead of reading it from a .env, never printing a value.
 Looks under each folder (the current one by default) down to 5 levels, skipping node_modules, vendor and .git, and leaves .example, .sample, .template and .dist files out. A folder it cannot read is named on stderr.
 With --fix, moves each secret a listed compose file writes out into the .env beside it as \${KEY}, puts it back when \`docker compose config\` resolves differently after, and shuts other accounts out of both files and of every listed .env; a key the .env already sets to another value stays put.
-Exits 1 when it finds one (with --fix, when one is left), 0 otherwise.`;
+Exits 0 when it finds none (with --fix, when none is left), 1 when it finds one, 2 on a usage error.`;
 var options = {
   json: jsonOption("the findings and the folders it could not read"),
   fix: { type: "boolean", description: "move inline compose secrets into a .env and shut other accounts out" }
@@ -1082,7 +1302,7 @@ var CHECKS = {
 };
 async function isFolder(path) {
   try {
-    return (await stat3(path)).isDirectory();
+    return (await stat4(path)).isDirectory();
   } catch {
     return false;
   }
@@ -1149,7 +1369,7 @@ async function audit2(args) {
   }
   const uid = process7.getuid?.();
   for (const { path, readable, tracked, secrets } of exposed) {
-    const sudo = uid !== undefined && uid !== 0 && (await stat3(path)).uid !== uid ? "sudo " : "";
+    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))}`] : [],
@@ -1165,10 +1385,14 @@ async function audit2(args) {
 // src/commands/compare.ts
 var diffUsage = `ev diff <a> <b>
 
-Names the keys set in one file and not the other, never their values. Exits 1 when they differ.`;
+Names the keys set in one file and not the other, never their values.
+
+Exits 0 when both set the same keys, 1 when they differ, 2 on a usage error.`;
 var missingUsage = `ev missing [file]
 
-Names the keys the reference file sets that the file (.env by default) does not. Exits 1 when some are missing.`;
+Names the keys the reference file sets that the file (.env by default) does not.
+
+Exits 0 when none is missing, 1 when some are, 2 on a usage error.`;
 async function keys(path) {
   return new Set(entries(await readEnv(path)).keys());
 }
@@ -1209,13 +1433,24 @@ var DEFAULT_FILE = ".env";
 var TRAILING_NEWLINE = /\r?\n$/;
 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.`;
+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.
+
+Exits 0 when it wrote the key, 1 when it could not, 2 on a usage error.`;
 var unsetUsage = `ev unset KEY [file]
 
-Removes every line setting KEY from the file (.env by default), leaving comments and other lines as they are.`;
+Removes every line setting KEY from the file (.env by default), leaving comments and other lines as they are.
+
+Exits 0 when it removed the key, 1 when the file does not set it, 2 on a usage error.`;
 var mvUsage = `ev mv KEY --from <file> --to <file>
 
-Moves KEY's line from one file to another, as written. Refuses to replace a key the target already sets unless --force.`;
+Moves KEY's line from one file to another, as written. Refuses to replace a key the target already sets unless --force.
+
+Exits 0 when it moved the key, 1 when the source lacks it or the target already sets it, 2 on a usage error.`;
+var cpUsage = `ev cp KEY --from <file> --to <file> [--as NEWKEY]
+
+Copies KEY's value from one file to another without printing it, replacing the key's line in the target in place or appending one, and prints the masked result as ev set does. --as stores the copy under another key.
+
+Exits 0 when it copied the key, 1 when the source lacks it, 2 on a usage error.`;
 async function readValue(from) {
   const input = await readInput(from ?? "-", { noStdin: "pipe the value on stdin or give -F <file>, it is never taken from the command line" });
   if (input === "")
@@ -1259,6 +1494,22 @@ ${unsetUsage}`);
   console.log(`${target}: removed ${key}`);
   return 0;
 }
+async function transfer(key, from, to, newKey, replace) {
+  if (from === to && newKey === undefined)
+    fail("--from and --to are the same file");
+  const source = await readEnv(from);
+  const line = lastLine(source, key);
+  if (line === undefined)
+    fail(`${key} is not set in ${from}`, 1);
+  const target = from === to ? source : await readOrEmpty(to);
+  const name = newKey ?? key;
+  if (!replace && entries(target).has(name))
+    fail(`${to} already sets ${name}, --force replaces it`, 1);
+  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 };
+}
 async function mv(args) {
   const parsed = parse(args, mvUsage, {
     from: { type: "string", description: "the file to take KEY from" },
@@ -1271,31 +1522,42 @@ async function mv(args) {
     fail(`needs KEY, --from and --to
 
 ${mvUsage}`);
-  if (from === to)
-    fail("--from and --to are the same file");
-  const source = await readEnv(from);
-  const line = lastLine(source, key);
-  if (line === undefined)
-    fail(`${key} is not set in ${from}`, 1);
-  const target = await readOrEmpty(to);
-  if (entries(target).has(key) && force !== true)
-    fail(`${to} already sets ${key}, --force replaces it`, 1);
-  setLine(target, key, line.value ?? "", line.raw);
-  await writeEnv(to, target);
+  const { source } = await transfer(key, from, to, undefined, force === true);
   removeKey(source, key);
   await writeEnv(from, source);
   console.log(`${key}: ${from} -> ${to}`);
   return 0;
 }
+async function cp(args) {
+  const parsed = parse(args, cpUsage, {
+    from: { type: "string", description: "the file to take KEY from" },
+    to: { type: "string", description: "the file to put the copy in, created when missing" },
+    as: { type: "string", description: "store the copy under this key instead" }
+  });
+  const [key] = parsed.positionals;
+  const { from, to, as } = parsed.values;
+  if (key === undefined || from === undefined || to === undefined)
+    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(`
+`, "\\n")}`);
+  return 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 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, KEY, PRIVATE or DSN, 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]
 
-Prints the masked value of one key, from every .env* file that sets it or from one 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(`
 `, "\\n").replaceAll("\r", "\\r");
@@ -1336,10 +1598,14 @@ ${getUsage}`);
 }
 var grepUsage = `ev grep [-i] <regex> [file...]
 
-Prints the keys matching the regular expression, from the folder's .env* files or the files given, with their values masked as ev list does. The regex is matched against the key only, never the value: \`ev grep '^DATABASE_'\` instead of \`grep ^DATABASE_ .env\`.`;
+Prints the keys matching the regular expression, from the folder's .env* files or the files given, with their values masked as ev list does. The regex is matched against the key only, never the value: \`ev grep '^DATABASE_'\` instead of \`grep ^DATABASE_ .env\`.
+
+Exits 0 when a key matches, 1 when none does, 2 on a usage error.`;
 var showUsage = `ev show <rev>:<file>
 
-Prints every key of an env file as a git revision holds it, values masked as ev list does: \`ev show HEAD~1:api/.env\` instead of \`git show HEAD~1:api/.env\`.`;
+Prints every key of an env file as a git revision holds it, values masked as ev list does: \`ev show HEAD~1:api/.env\` instead of \`git show HEAD~1:api/.env\`.
+
+Exits 0 when it printed them, 1 when git cannot show the file, 2 on a usage error.`;
 var REVISION = /^([^:]+):(.+)$/;
 async function grep(args) {
   const parsed = parse(args, grepUsage, { "ignore-case": { type: "boolean", short: "i", description: "match the key whatever its case" } });
@@ -1389,6 +1655,8 @@ process8.exitCode = await runCli({
   name: "ev",
   version,
   about: ".env files listed and edited with secrets masked",
+  replaces: "cat .env, grep on env files and editing them by hand",
+  examples: ["ev list", ["ev get DATABASE_URL", "one key, its value masked"]],
   commands: {
     list: { run: list, summary: "every key of the .env* files, secrets masked" },
     get: { run: get, summary: "one key's masked value" },
@@ -1396,6 +1664,7 @@ process8.exitCode = await runCli({
     show: { run: show, summary: "an env file at a git revision, values masked" },
     set: { run: set, summary: "set a key, the value read from stdin or -F" },
     unset: { run: unset, summary: "remove a key from a file" },
+    cp: { run: cp, summary: "copy a key from one file to another, the value never printed" },
     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" },