@kaynooo/env-tools 0.4.1 → 0.6.0

package/dist/redact.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 previous[b.length] ?? 0;
+  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 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,14 +752,15 @@ 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/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;
@@ -721,6 +883,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) {
@@ -744,6 +917,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)) {
@@ -755,6 +961,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]) });
@@ -796,7 +1003,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 = [];
@@ -911,14 +1131,16 @@ function check(text, known) {
 // src/redact.ts
 var usage = `redact [--check]
 
-Copies stdin to stdout line by line with secrets masked: known token formats (ghp_, github_pat_, glpat-, sk-, xox?-, JWTs), private key blocks, the password of any URL and the values of secret-looking keys in this folder's .env* files.
---check prints nothing of the input and lists the file and line of each secret found, exiting 1 when there is any: \`git diff --cached | redact --check\`.`;
+Copies stdin to stdout line by line with secrets masked: known token formats (ghp_, github_pat_, glpat-, sk-, xox?-, JWTs), private key blocks, the password and the tokens of any URL and the values of secret-looking keys in this folder's .env* files.
+--check prints nothing of the input and lists the file and line of each secret found, exiting 1 when there is any: \`git diff --cached | redact --check\`.
+
+Exits 0 when it copied the input or found no secret, 1 when --check finds one, 2 on a usage error.`;
 var options = {
   check: { type: "boolean", description: "list where secrets are instead of masking them, exit 1 when found" },
   "no-env": { type: "boolean", description: "do not search for the values of the .env* files" }
 };
 async function run(args) {
-  const parsed = parse(args, usage, options);
+  const parsed = parse(args, usage, options, { replaces: "printing a command's secrets into a log or a transcript", examples: [["docker compose config | redact", "the resolved compose file, secrets masked"], ["git diff --cached | redact --check", "refuse a commit carrying a secret"]] });
   const known = parsed.values["no-env"] === true ? undefined : await loadKnown();
   if (parsed.values.check === true) {
     const findings = check(await readInput("-"), known);

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@kaynooo/env-tools",
   "type": "module",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "ev lists and edits .env files with secrets masked, redact masks secrets in any piped output.",
-  "author": "Kaynooo <kaynooo@kevyn.fr>",
+  "author": "Kaynooo <contact@kaynooo.fr>",
   "license": "MIT",
-  "homepage": "https://git.kevyn.fr/kaynooo/agent-tools/src/branch/main/packages/env#readme",
+  "homepage": "https://git.kaynooo.fr/kaynooo/agent-tools/src/branch/main/packages/env#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://git.kevyn.fr/kaynooo/agent-tools.git",
+    "url": "git+https://git.kaynooo.fr/kaynooo/agent-tools.git",
     "directory": "packages/env"
   },
-  "bugs": "https://git.kevyn.fr/kaynooo/agent-tools/issues",
+  "bugs": "https://git.kaynooo.fr/kaynooo/agent-tools/issues",
   "keywords": ["env", "dotenv", "secrets", "redact", "mask"],
   "exports": {
     "./dotenv": "./src/dotenv.ts",
@@ -26,7 +26,7 @@
     "bun": ">=1.4.3"
   },
   "publishConfig": {
-    "registry": "https://git.kevyn.fr/api/packages/kaynooo/npm/"
+    "registry": "https://git.kaynooo.fr/api/packages/kaynooo/npm/"
   },
   "scripts": {
     "build": "$npm_execpath build src/ev.ts src/redact.ts --target bun --outdir dist",