@kaynooo/env-tools 0.0.0-stage → 0.4.1

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@kaynooo/env-tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "type": "module",
+  "version": "0.4.1",
+  "description": "ev lists and edits .env files with secrets masked, redact masks secrets in any piped output.",
+  "author": "Kaynooo <kaynooo@kevyn.fr>",
+  "license": "MIT",
+  "homepage": "https://git.kevyn.fr/kaynooo/agent-tools/src/branch/main/packages/env#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.kevyn.fr/kaynooo/agent-tools.git",
+    "directory": "packages/env"
+  },
+  "bugs": "https://git.kevyn.fr/kaynooo/agent-tools/issues",
+  "keywords": ["env", "dotenv", "secrets", "redact", "mask"],
+  "exports": {
+    "./dotenv": "./src/dotenv.ts",
+    "./guard": "./src/guard.ts"
+  },
+  "bin": {
+    "ev": "./dist/ev.js",
+    "redact": "./dist/redact.js"
+  },
+  "files": ["dist", "src/dotenv.ts"],
+  "engines": {
+    "bun": ">=1.4.3"
+  },
+  "publishConfig": {
+    "registry": "https://git.kevyn.fr/api/packages/kaynooo/npm/"
+  },
+  "scripts": {
+    "build": "$npm_execpath build src/ev.ts src/redact.ts --target bun --outdir dist",
+    "ev": "$npm_execpath src/ev.ts",
+    "redact": "$npm_execpath src/redact.ts"
+  },
+  "devDependencies": {
+    "@kaynooo/cli-kit": "workspace:*"
+  }
+}

package/src/dotenv.ts

@@ -0,0 +1,152 @@
+// One logical line of a .env file: a comment, a blank or an unparsed line (no key), or an assignment whose raw text may span several physical lines.
+export interface DotenvLine {
+  raw: string
+  key?: string
+  value?: string
+}
+
+export interface Dotenv {
+  lines: DotenvLine[]
+}
+
+const ASSIGNMENT = /^\s*(?:export\s+)?([A-Z_][\w.-]*)\s*=(.*)$/i
+const EXPORTED = /^\s*export\s/
+const INLINE_COMMENT = /\s+#.*$/
+const CARRIAGE_RETURN = /\r$/
+const ESCAPES: Record<string, string> = { 'n': '\n', 'r': '\r', 't': '\t', '"': '"', '\\': '\\' }
+const NEEDS_QUOTES = /[\s#"'\\$`]/
+
+// Finds the closing quote, skipping backslash escapes inside double quotes. Returns -1 when the value continues on the next line.
+function closingQuote(text: string, quote: string): number {
+  for (let index = 0; index < text.length; index++) {
+    if (quote === '"' && text[index] === '\\')
+      index++
+    else if (text[index] === quote)
+      return index
+  }
+
+  return -1
+}
+
+function unescapeDouble(text: string): string {
+  let out = ''
+
+  for (let index = 0; index < text.length; index++) {
+    const next = text[index + 1]
+
+    if (text[index] === '\\' && next !== undefined && next in ESCAPES) {
+      out += ESCAPES[next]
+      index++
+    }
+    else {
+      out += text[index]
+    }
+  }
+
+  return out
+}
+
+export function parseDotenv(text: string): Dotenv {
+  const physical = text.split('\n')
+  const lines: DotenvLine[] = []
+
+  for (let index = 0; index < physical.length; index++) {
+    const line = physical[index] ?? ''
+    const match = ASSIGNMENT.exec(line.replace(CARRIAGE_RETURN, ''))
+
+    if (match === null) {
+      lines.push({ raw: line })
+
+      continue
+    }
+
+    const [, key = '', rest = ''] = match
+    const start = rest.trimStart()
+    const quote = start[0]
+
+    if (quote !== '"' && quote !== '\'' && quote !== '`') {
+      lines.push({ raw: line, key, value: start.replace(INLINE_COMMENT, '').trim() })
+
+      continue
+    }
+
+    let body = start.slice(1)
+    let raw = line
+    let end = closingQuote(body, quote)
+
+    while (end === -1 && index + 1 < physical.length) {
+      index++
+      body += `\n${(physical[index] ?? '').replace(CARRIAGE_RETURN, '')}`
+      raw += `\n${physical[index] ?? ''}`
+      end = closingQuote(body, quote)
+    }
+
+    const inner = end === -1 ? body : body.slice(0, end)
+
+    lines.push({ raw, key, value: quote === '"' ? unescapeDouble(inner) : inner })
+  }
+
+  return { lines }
+}
+
+export function serializeDotenv(file: Dotenv): string {
+  return file.lines.map(line => line.raw).join('\n')
+}
+
+// The effective entries: a repeated key keeps its last value, as dotenv loaders do.
+export function entries(file: Dotenv): Map<string, string> {
+  const map = new Map<string, string>()
+
+  for (const line of file.lines) {
+    if (line.key !== undefined)
+      map.set(line.key, line.value ?? '')
+  }
+
+  return map
+}
+
+export function formatAssignment(key: string, value: string): string {
+  if (value === '' || !NEEDS_QUOTES.test(value))
+    return `${key}=${value}`
+
+  const escaped = value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('\r', '\\r').replaceAll('\n', '\\n')
+
+  return `${key}="${escaped}"`
+}
+
+// Replaces the last assignment of a key keeping its `export`, or appends before the trailing newline. `raw` is the whole line to store when given.
+export function setLine(file: Dotenv, key: string, value: string, raw?: string): void {
+  const index = file.lines.findLastIndex(line => line.key === key)
+  const existing = file.lines[index]
+
+  if (existing !== undefined) {
+    const exported = EXPORTED.test(existing.raw) ? 'export ' : ''
+
+    file.lines[index] = { raw: raw ?? `${exported}${formatAssignment(key, value)}`, key, value }
+
+    return
+  }
+
+  const line = { raw: raw ?? formatAssignment(key, value), key, value }
+  const last = file.lines.at(-1)
+
+  if (last === undefined)
+    file.lines.push(line, { raw: '' })
+  else if (last.raw === '')
+    file.lines.splice(-1, 0, line)
+  else
+    file.lines.push(line, { raw: '' })
+}
+
+// Drops every assignment of the key and returns how many went.
+export function removeKey(file: Dotenv, key: string): number {
+  const before = file.lines.length
+
+  file.lines = file.lines.filter(line => line.key !== key)
+
+  return before - file.lines.length
+}
+
+export function lastLine(file: Dotenv, key: string): DotenvLine | undefined {
+  return file.lines.findLast(line => line.key === key)
+}