@kaynooo/cli-env 0.8.1 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,107 @@
1
+ import type { Piece, Word } from '@kaynooo/cli-kit/shell'
2
+ import { braceExpand, parseCommand, splitCommand, tokenize, words } from '@kaynooo/cli-kit/shell'
3
+ import { GIT_EXCLUDE } from './guard-dumps'
4
+ import { isEnvFile, namesEnvFile } from './guard-paths'
5
+ import { GREP_VALUE_OPTIONS, GREPS, listsFiles, patternIndex, printsNamesOnly, RG_VALUE_OPTIONS } from './guard-search'
6
+
7
+ const ENV_NAME_IN_CODE = /(?:^|[^\w.-])(\.env(?:\.[\w.-]*\w)?|\.envrc)(?![\w-])/g
8
+ const PYTHON_ENVIRON = /\bos\.environ\b(?!\s*(?:\[|\.get\b))/
9
+ const VARIABLE = /\$(?:(\w+)|\{(\w+)\})/
10
+ const ASSIGNMENT = /^\w+=/
11
+ const MAX_VARIANTS = 64
12
+ // Programs running the code they are given, which may read an env file or print the environment.
13
+ const INTERPRETERS = new Set(['bun', 'deno', 'node', 'python', 'python3', 'ruby', 'perl', 'php', 'lua', 'awk', 'gawk'])
14
+ const CODE_OPTIONS = new Set(['-e', '-c', '-p', '-E', '-pe', '-r', '--eval', '--print', '--command'])
15
+ // What a script needs to open a file or run a command: file, process and shell APIs, imports, command substitution and backticks.
16
+ const CAN_REACH_FILES = /read|write|open|exec|spawn|system|popen|import|require|eval|load|fetch|glob|stream|source|getline|constructor|file(?!s\b)|\bcat\b|\b(?:Bun|Deno|fs|os|io|sh|bash|process|globalThis|window|Function|qx)\b|\$\s*[`({]|`/i
17
+ const DECLARERS = new Set(['export', 'declare', 'local', 'readonly', 'typeset'])
18
+ // Programs that name an env file without reading it: listing, testing, or loading it into a process that prints nothing.
19
+ const HARMLESS = new Set(['ev', 'redact', 'ls', 'stat', 'test', '[', '[[', 'touch'])
20
+ const GIT_HARMLESS = new Set(['check-ignore', 'ls-files', 'status'])
21
+
22
+ // The values each variable is given in a command, by assignment, `export` or a `for` list.
23
+ export function variablesOf(command: string): Map<string, string[]> {
24
+ const variables = new Map<string, string[]>()
25
+ const add = (assignment: string) => {
26
+ const at = assignment.indexOf('=')
27
+ const name = assignment.slice(0, at)
28
+
29
+ variables.set(name, [...variables.get(name) ?? [], assignment.slice(at + 1)])
30
+ }
31
+
32
+ for (const piece of splitCommand(command)) {
33
+ const { program, args, assignments } = parseCommand(piece.command)
34
+ const tokens = tokenize(piece.command)
35
+
36
+ const declared = DECLARERS.has(program) ? args.filter(arg => ASSIGNMENT.test(arg)) : []
37
+
38
+ for (const assignment of [...assignments, ...declared])
39
+ add(assignment)
40
+
41
+ if (tokens[0] === 'for' && tokens[2] === 'in' && tokens[1] !== undefined)
42
+ variables.set(tokens[1], [...variables.get(tokens[1]) ?? [], ...tokens.slice(3)])
43
+ }
44
+
45
+ return variables
46
+ }
47
+
48
+ // The words a word stands for once the variables it uses and its `{a,b}` lists are replaced.
49
+ function variantsOf(word: Word, variables: ReadonlyMap<string, string[]>): string[] {
50
+ let found = [word.text]
51
+
52
+ for (let round = 0; round < 4 && found.some(each => VARIABLE.test(each)); round++) {
53
+ found = found.flatMap((each) => {
54
+ const match = VARIABLE.exec(each)
55
+ const values = variables.get(match?.[1] ?? match?.[2] ?? '')
56
+
57
+ if (match === null || values === undefined)
58
+ return [each.replace(VARIABLE, '')]
59
+
60
+ return values.map(value => each.slice(0, match.index) + value + each.slice(match.index + match[0].length))
61
+ }).slice(0, MAX_VARIANTS)
62
+ }
63
+
64
+ return found.flatMap(each => word.hasBrace ? braceExpand(each) : [each])
65
+ }
66
+
67
+ // Whether code names an env file and could open it: a mention in code that calls nothing able to read a file, run a command or import a module (`/\.env files/.test(x)`) is only text. Deliberately generous, so a doubtful script stays refused.
68
+ function codeReadsEnvFile(code: string): boolean {
69
+ return [...code.matchAll(ENV_NAME_IN_CODE)].some(match => isEnvFile(match[1] ?? '')) && CAN_REACH_FILES.test(code)
70
+ }
71
+
72
+ // Whether code run by an interpreter, given as an argument or fed as a heredoc, reads an env file or dumps the environment of a Python process.
73
+ function codeReadsEnv(found: readonly Word[], heredocs: readonly string[]): boolean {
74
+ const sources = [...found.filter((word, i) => word.isProse || CODE_OPTIONS.has(found[i - 1]?.text ?? '')).map(word => word.text), ...heredocs]
75
+
76
+ return sources.some(code => PYTHON_ENVIRON.test(code) || codeReadsEnvFile(code))
77
+ }
78
+
79
+ export function readsEnv(piece: Piece, variables: ReadonlyMap<string, string[]>): boolean {
80
+ const { program, args } = parseCommand(piece.command)
81
+
82
+ if (program === '' || HARMLESS.has(program) || (program === 'git' && GIT_HARMLESS.has(args[0] ?? '')))
83
+ return false
84
+
85
+ if (INTERPRETERS.has(program) && codeReadsEnv(words(piece.command), piece.heredocs))
86
+ return true
87
+
88
+ if (printsNamesOnly(program, args) || listsFiles(program, args))
89
+ return false
90
+
91
+ return namesEnv(piece, variables)
92
+ }
93
+
94
+ // Whether a piece has a word naming an env file, whatever it does with it.
95
+ export function namesEnv(piece: Piece, variables: ReadonlyMap<string, string[]>): boolean {
96
+ const { program, args } = parseCommand(piece.command)
97
+ const found = words(piece.command)
98
+
99
+ // a git pathspec like `:!.env` leaves the file out
100
+ const isExclusion = (word: Word) => program === 'git' && GIT_EXCLUDE.test(word.text)
101
+ // the pattern of a search is a regex, not a file
102
+ const isSearch = GREPS.has(program) || program === 'rg' || program === 'ag'
103
+ const patternAt = isSearch ? patternIndex(args, GREPS.has(program) ? GREP_VALUE_OPTIONS : RG_VALUE_OPTIONS) : undefined
104
+ const pattern = patternAt === undefined ? undefined : found.length - args.length + patternAt
105
+
106
+ return found.some((word, index) => index !== pattern && !word.isProse && !isExclusion(word) && variantsOf(word, variables).some(variant => namesEnvFile(variant, found[index - 1]?.text, word.hasGlob)))
107
+ }
@@ -0,0 +1,80 @@
1
+ import { braceExpand } from '@kaynooo/cli-kit/shell'
2
+ import { ENV_FILE, TEMPLATE } from './files'
3
+
4
+ const REDIRECT = /^\d*[<>]+&?/
5
+ const ENVRC = '.envrc'
6
+ const PROC_ENVIRON = /^\/proc\/[^/]+\/environ$/
7
+ // Names a glob could stand for, to tell whether it reaches an env file.
8
+ const ENV_SAMPLES = ['.env', '.env.local', '.env.production', '.envrc']
9
+ const REGEX_SPECIALS = /[.+^${}()|\\[\]]/g
10
+ const NEGATED_CLASS = /^!/
11
+ const GLOB_CHAR = /[*?[]/
12
+
13
+ export const EXCLUDE_OPTIONS = new Set(['--exclude', '--exclude-dir', '-g', '--glob', '--iglob'])
14
+
15
+ // The name past the last `/`, or past the `:` of `HEAD~1:api/.env` as git spells a file at a revision; the `.env*` glob reaches one too.
16
+ export function isEnvFile(path: string): boolean {
17
+ const name = path.slice(Math.max(path.lastIndexOf('/'), path.lastIndexOf(':')) + 1)
18
+
19
+ return (ENV_FILE.test(name) || name === '.env*' || name === ENVRC) && !TEMPLATE.test(name)
20
+ }
21
+
22
+ // The regex a shell glob stands for, `*` and `?` matching a name's characters and `[...]` a class.
23
+ function globRegex(glob: string): RegExp {
24
+ let source = ''
25
+
26
+ for (let i = 0; i < glob.length; i++) {
27
+ const char = glob[i] ?? ''
28
+ const close = char === '[' ? glob.indexOf(']', i + 2) : -1
29
+
30
+ if (char === '*') {
31
+ source += '.*'
32
+ }
33
+ else if (char === '?') {
34
+ source += '.'
35
+ }
36
+ else if (close === -1) {
37
+ source += char.replace(REGEX_SPECIALS, String.raw`\$&`)
38
+ }
39
+ else {
40
+ source += `[${glob.slice(i + 1, close).replace(NEGATED_CLASS, '^')}]`
41
+ i = close
42
+ }
43
+ }
44
+
45
+ return new RegExp(`^${source}$`)
46
+ }
47
+
48
+ // A dotted glob such as `.en?` or `.e*` reaching an env file; the shell never matches a leading dot with a wildcard, so the glob has to spell it.
49
+ function globReachesEnv(path: string): boolean {
50
+ const name = path.slice(path.lastIndexOf('/') + 1)
51
+
52
+ if (!name.startsWith('.') || !GLOB_CHAR.test(name))
53
+ return false
54
+
55
+ const regex = globRegex(name)
56
+
57
+ return ENV_SAMPLES.some(sample => regex.test(sample))
58
+ }
59
+
60
+ // Whether the path or glob a file tool is given reaches an env file, `{a,b}` lists and wildcards included.
61
+ export function reachesEnvFile(path: string): boolean {
62
+ return braceExpand(path).some(each => isEnvFile(each) || globReachesEnv(each))
63
+ }
64
+
65
+ // The path a word stands for, past any redirect and `--flag=` prefix.
66
+ function targetOf(word: string): string {
67
+ const bare = word.replace(REDIRECT, '')
68
+
69
+ return bare.includes('=') ? bare.slice(bare.indexOf('=') + 1) : bare
70
+ }
71
+
72
+ // A word naming an env file, past any redirect and `--flag=` prefix; an `--env-file` value only loads it, so it is let through.
73
+ export function namesEnvFile(word: string, previous: string | undefined, isGlob: boolean): boolean {
74
+ if (previous === '--env-file' || word.startsWith('--env-file=') || word.startsWith('--exclude') || EXCLUDE_OPTIONS.has(previous ?? ''))
75
+ return false
76
+
77
+ const path = targetOf(word)
78
+
79
+ return isEnvFile(path) || PROC_ENVIRON.test(path) || (isGlob && globReachesEnv(path))
80
+ }
@@ -0,0 +1,76 @@
1
+ import type { Piece } from '@kaynooo/cli-kit/shell'
2
+ import { parseCommand, tokenize } from '@kaynooo/cli-kit/shell'
3
+ import { namesEnv } from './guard-names'
4
+ import { searchesEnvNames } from './guard-search'
5
+
6
+ // Programs an `xargs` can run on a listing of names without printing a line of the files.
7
+ const XARGS_SAFE = new Set(['ls', 'stat', 'wc', 'test', '[', 'touch', 'echo', 'printf', 'basename', 'dirname', 'ev', 'redact', ''])
8
+ // GNU parallel's options taking their value as the next word, before the command it runs.
9
+ const PARALLEL_VALUE_OPTIONS = new Set(['-j', '--jobs', '-P', '--max-procs', '-S', '--sshlogin', '-C', '--colsep', '-n', '--max-args', '-N', '-d', '--delimiter', '-E', '-I', '--timeout', '--delay', '--joblog', '--results', '--tmpdir', '-a', '--arg-file', '--halt', '--retries', '--tag-string'])
10
+ const IDENTIFIER = /^[A-Z_]\w*$/i
11
+ // `read`'s options taking a value, which is not a variable it fills.
12
+ const READ_VALUE_OPTIONS = new Set(['-a', '-d', '-i', '-n', '-N', '-p', '-t', '-u'])
13
+
14
+ // Whether a piece further up the pipeline that `index` starts lists env files by name.
15
+ function listsEnvUpstream(pieces: readonly Piece[], index: number, variables: ReadonlyMap<string, string[]>): boolean {
16
+ for (let at = index - 1; at >= 0 && pieces[at]?.separator.startsWith('|'); at--) {
17
+ if (namesEnv(pieces[at] as Piece, variables) || searchesEnvNames(pieces[at] as Piece))
18
+ return true
19
+ }
20
+
21
+ return false
22
+ }
23
+
24
+ // The program GNU parallel runs on each name it is fed, `cat` in `parallel -j4 cat {}`.
25
+ function parallelRunner(args: readonly string[]): string {
26
+ const at = args.findIndex((arg, i) => !arg.startsWith('-') && !PARALLEL_VALUE_OPTIONS.has(args[i - 1] ?? ''))
27
+
28
+ return at === -1 ? '' : (args[at] ?? '').split('/').at(-1) ?? ''
29
+ }
30
+
31
+ // Whether the piece is an `xargs` or `parallel` running a command that may print the files it is given the names of, on a listing naming an env file further up its pipeline (harmless alone, but each name gets opened).
32
+ export function runnerReadsListedEnv(pieces: readonly Piece[], index: number, variables: ReadonlyMap<string, string[]>): boolean {
33
+ const command = pieces[index]?.command ?? ''
34
+ const { program, args, isWrapped } = parseCommand(command)
35
+ // parseCommand sees through `xargs` and `parallel` to the command they run
36
+ const isXargs = isWrapped && tokenize(command).some(word => word === 'xargs' || word === 'parallel')
37
+
38
+ if (program !== 'parallel' && !isXargs)
39
+ return false
40
+
41
+ return !XARGS_SAFE.has(isXargs ? program : parallelRunner(args)) && listsEnvUpstream(pieces, index, variables)
42
+ }
43
+
44
+ // The variables a `read` fills, REPLY when it names none.
45
+ function readVariables(args: readonly string[]): string[] {
46
+ const names = args.filter((arg, i) => !arg.startsWith('-') && !READ_VALUE_OPTIONS.has(args[i - 1] ?? '') && IDENTIFIER.test(arg))
47
+
48
+ return names.length === 0 ? ['REPLY'] : names
49
+ }
50
+
51
+ // Whether the piece sits in the body of a `while read` loop fed a listing naming an env file, and hands one of the names read to a command that may print the file.
52
+ export function loopReadsListedEnv(pieces: readonly Piece[], index: number, variables: ReadonlyMap<string, string[]>): boolean {
53
+ const { program } = parseCommand(pieces[index]?.command ?? '')
54
+
55
+ if (XARGS_SAFE.has(program) || program === 'done')
56
+ return false
57
+
58
+ for (let at = index - 1; at >= 0; at--) {
59
+ const piece = pieces[at] as Piece
60
+ const head = parseCommand(piece.command)
61
+
62
+ if (head.program === 'done')
63
+ return false
64
+
65
+ const opener = tokenize(piece.command)[0]
66
+
67
+ if (head.program !== 'read' || (opener !== 'while' && opener !== 'until'))
68
+ continue
69
+
70
+ const used = readVariables(head.args).some(name => new RegExp(`\\$\\{?${name}\\b`).test(pieces[index]?.command ?? ''))
71
+
72
+ return used && listsEnvUpstream(pieces, at, variables)
73
+ }
74
+
75
+ return false
76
+ }
@@ -0,0 +1,181 @@
1
+ import type { Piece } from '@kaynooo/cli-kit/shell'
2
+ import { parseCommand } from '@kaynooo/cli-kit/shell'
3
+ import { EXCLUDE_OPTIONS } from './guard-paths'
4
+
5
+ const ENV_NAME_IN_PATTERN = /(?:^|[^\w-])\.env(?![\w-])/
6
+ const SHORT_FLAGS = /^-[a-z]+$/i
7
+
8
+ export const GREPS = new Set(['grep', 'egrep', 'fgrep'])
9
+ export const GREP_VALUE_OPTIONS = new Set(['-e', '-f', '-m', '-A', '-B', '-C', '-d', '-D', '--regexp', '--file', '--max-count', '--include', '--exclude', '--exclude-dir', '--exclude-from', '--context', '--after-context', '--before-context', '--label', '--binary-files', '--directories', '--devices'])
10
+ export const RG_VALUE_OPTIONS = new Set(['-e', '-f', '-g', '-t', '-T', '-m', '-A', '-B', '-C', '-j', '-d', '-r', '-M', '-E', '--replace', '--max-columns', '--encoding', '--regexp', '--file', '--glob', '--iglob', '--type', '--type-not', '--max-count', '--context', '--after-context', '--before-context', '--threads', '--max-depth', '--max-filesize'])
11
+ const PATTERN_OPTIONS = new Set(['-e', '-f', '--regexp', '--file'])
12
+ // rg's -L follows links, it does not list the files without a match
13
+ const GREP_NAMES_ONLY = new Set('lLcq')
14
+ const RG_NAMES_ONLY = new Set('lcq')
15
+ const NAMES_ONLY_LONG = new Set(['--files-with-matches', '--files-without-match', '--count', '--count-matches', '--quiet', '--silent'])
16
+ const FIND_ACTIONS = new Set(['-exec', '-execdir', '-ok', '-okdir', '-delete', '-fprint', '-fprint0', '-fprintf', '-fls', '-files0-from'])
17
+ const HIDDEN_FLAGS = /^(?:-u{2,}|--hidden|-\.)$/i
18
+ const HAS_R = /r/i
19
+ // A directory listing everything under it: the current one, its parents, home, the root.
20
+ const WHOLE_TREE_OPERAND = /^(?:(?:\.\.?\/?)+|~\/?|\$HOME\/?|\/)$/
21
+ // An option leaving env files out of a search: grep's `--exclude=.env*`, ripgrep's `-g '!.env*'`.
22
+ const EXCLUDES_ENV = /^(?:--exclude(?:-dir)?=.*env|(?:--glob=|--iglob=|-g)?!.*env)/
23
+
24
+ // Whether a piece is a grep-family search, which the refusal then advises on.
25
+ export function isSearchCommand(piece: Piece): boolean {
26
+ const { program } = parseCommand(piece.command)
27
+
28
+ return GREPS.has(program) || program === 'rg' || program === 'ag'
29
+ }
30
+
31
+ // Whether the grep family lists file names or counts matches only (`grep -l`, `-L`, `-c`, `-q`), which prints no line of a file.
32
+ export function printsNamesOnly(program: string, args: readonly string[]): boolean {
33
+ const isGrep = GREPS.has(program)
34
+
35
+ if (!isGrep && program !== 'rg')
36
+ return false
37
+
38
+ const valueOptions = isGrep ? GREP_VALUE_OPTIONS : RG_VALUE_OPTIONS
39
+ const valueLetters = valueLettersOf(valueOptions)
40
+ const namesOnly = isGrep ? GREP_NAMES_ONLY : RG_NAMES_ONLY
41
+ // the word after an option taking a value is that value, never a flag: `grep -e -l .env` prints lines
42
+ let isValue = false
43
+
44
+ for (const arg of args) {
45
+ if (isValue) {
46
+ isValue = false
47
+
48
+ continue
49
+ }
50
+
51
+ if (arg === '--')
52
+ return false
53
+
54
+ if (NAMES_ONLY_LONG.has(arg))
55
+ return true
56
+
57
+ if (valueOptions.has(arg)) {
58
+ isValue = true
59
+
60
+ continue
61
+ }
62
+
63
+ if (!SHORT_FLAGS.test(arg))
64
+ continue
65
+
66
+ // a cluster ends at the first option taking a value, which swallows the rest of it or else the next word
67
+ for (const [i, letter] of [...arg.slice(1)].entries()) {
68
+ if (valueLetters.has(letter)) {
69
+ isValue = i === arg.length - 2
70
+
71
+ break
72
+ }
73
+
74
+ if (namesOnly.has(letter))
75
+ return true
76
+ }
77
+ }
78
+
79
+ return false
80
+ }
81
+
82
+ // `find` only printing the names it matches, with no action that runs a command or writes a file.
83
+ export function listsFiles(program: string, args: readonly string[]): boolean {
84
+ return program === 'find' && !args.some(arg => FIND_ACTIONS.has(arg))
85
+ }
86
+
87
+ // The letters of the short options taking a value.
88
+ function valueLettersOf(valueOptions: ReadonlySet<string>): Set<string> {
89
+ return new Set([...valueOptions].filter(option => option.length === 2 && !option.startsWith('--')).map(option => option.slice(1)))
90
+ }
91
+
92
+ // The index in `args` of the pattern a search program is given, undefined when `-e` or `-f` gives it, even glued to a cluster as in `-ne KEY`: it is a regex, never a file.
93
+ export function patternIndex(args: readonly string[], valueOptions: ReadonlySet<string>): number | undefined {
94
+ const valueLetters = valueLettersOf(valueOptions)
95
+
96
+ for (let i = 0; i < args.length; i++) {
97
+ const arg = args[i] ?? ''
98
+
99
+ if (arg.startsWith('--regexp=') || arg.startsWith('--file='))
100
+ return undefined
101
+
102
+ if (!arg.startsWith('-') || arg === '-')
103
+ return i
104
+
105
+ if (arg.startsWith('--')) {
106
+ if (PATTERN_OPTIONS.has(arg))
107
+ return undefined
108
+
109
+ if (valueOptions.has(arg))
110
+ i++
111
+
112
+ continue
113
+ }
114
+
115
+ // a cluster of short options ends at the first one taking a value, glued after it or the next word
116
+ const at = [...arg.slice(1)].findIndex(letter => valueLetters.has(letter))
117
+ const letter = arg[at + 1]
118
+
119
+ if (at === -1)
120
+ continue
121
+
122
+ if (letter === 'e' || letter === 'f')
123
+ return undefined
124
+
125
+ if (at === arg.length - 2)
126
+ i++
127
+ }
128
+
129
+ return undefined
130
+ }
131
+
132
+ // The operands of a search program: its words less the options, their values and the pattern, which `-e` or `-f` may have already given.
133
+ function operandsOf(args: readonly string[], valueOptions: ReadonlySet<string>): string[] {
134
+ const operands: string[] = []
135
+ let hasPattern = false
136
+
137
+ for (let i = 0; i < args.length; i++) {
138
+ const arg = args[i] ?? ''
139
+
140
+ if (PATTERN_OPTIONS.has(arg) || arg.startsWith('--regexp=') || arg.startsWith('--file='))
141
+ hasPattern = true
142
+
143
+ if (valueOptions.has(arg))
144
+ i++
145
+ else if (!arg.startsWith('-'))
146
+ operands.push(arg)
147
+ }
148
+
149
+ return hasPattern ? operands : operands.slice(1)
150
+ }
151
+
152
+ // Whether a search over a whole tree would open an env file: a recursive grep, or ripgrep and ag told to look at hidden files, which they skip by default.
153
+ export function searchesEnv(program: string, args: readonly string[]): boolean {
154
+ const isGrep = GREPS.has(program)
155
+
156
+ if ((!isGrep && program !== 'rg' && program !== 'ag') || printsNamesOnly(program, args))
157
+ return false
158
+
159
+ const isRecursive = args.some(arg => (SHORT_FLAGS.test(arg) && HAS_R.test(arg)) || arg === '--recursive' || arg === '--dereference-recursive')
160
+ const isHidden = args.some(arg => HIDDEN_FLAGS.test(arg) || (program === 'ag' && (arg === '-u' || arg === '--unrestricted')))
161
+ const isLimited = args.some((arg, i) => arg.startsWith('--include') || EXCLUDES_ENV.test(arg) || (EXCLUDE_OPTIONS.has(args[i - 1] ?? '') && arg.includes('env')))
162
+
163
+ if (isLimited || (isGrep ? !isRecursive : !isHidden))
164
+ return false
165
+
166
+ const operands = operandsOf(args, isGrep ? GREP_VALUE_OPTIONS : RG_VALUE_OPTIONS)
167
+
168
+ return operands.length === 0 || operands.some(operand => WHOLE_TREE_OPERAND.test(operand))
169
+ }
170
+
171
+ // Whether the piece is a search whose pattern, its escapes dropped, names an env file (`grep '^\.env'`): fed a listing, what it prints are env file names.
172
+ export function searchesEnvNames(piece: Piece): boolean {
173
+ const { program, args } = parseCommand(piece.command)
174
+
175
+ if (!GREPS.has(program) && program !== 'rg')
176
+ return false
177
+
178
+ const at = patternIndex(args, GREPS.has(program) ? GREP_VALUE_OPTIONS : RG_VALUE_OPTIONS)
179
+
180
+ return at !== undefined && ENV_NAME_IN_PATTERN.test((args[at] ?? '').replaceAll('\\', ''))
181
+ }
package/src/guard.ts ADDED
@@ -0,0 +1,51 @@
1
+ import type { Piece } from '@kaynooo/cli-kit/shell'
2
+ import { parseCommand, splitCommand, substitutions, tokenize } from '@kaynooo/cli-kit/shell'
3
+ import { dumpsContainerEnv, dumpsEnvironment, printsTrackedEnv } from './guard-dumps'
4
+ import { readsEnv, variablesOf } from './guard-names'
5
+ import { loopReadsListedEnv, runnerReadsListedEnv } from './guard-pipes'
6
+ import { searchesEnv } from './guard-search'
7
+
8
+ // Code printing the whole environment Bun filled from the .env files.
9
+ const ENV_DUMP = /(?:console\.\w+|JSON\.stringify|Object\.(?:entries|keys|values)|print)\(\s*process\.env\s*[,)]/
10
+
11
+ export const USE_EV = '.env files hold secrets that must never reach the transcript, so they are not read, edited or printed directly. Use `ev` instead: `ev list`, `ev get KEY` (masked), `ev grep <regex>` for the keys matching it, `ev show <rev>:<file>` for one at a git revision, `printf %s "$value" | ev set KEY [file]` (`--empty` for an empty value), `ev unset KEY`, `ev cp KEY --from .env --to .env.local`, `ev mv KEY --from .env --to .env.local`, `ev diff a b`, `ev missing`; and pipe output that may carry a secret through `redact`, as `docker compose exec <svc> printenv | redact` or `docker compose config | redact`. If `ev` is missing: `bun install -g @kaynooo/cli-env`.'
12
+
13
+ export const USE_EV_SEARCH = 'To search them, `ev grep <regex>` prints the matching keys, masked. `grep -l`, `-L` and `-c` (file names and counts) are allowed, and a tree-wide search can run as `rg <regex>`, which skips gitignored files, or `grep -r --exclude=\'.env*\' <regex> .`.'
14
+
15
+ // The pieces of a command that would read, write or print an env file or the whole environment.
16
+ export function touchingPieces(command: string, options: { hasTrackedEnv?: boolean } = {}): Piece[] {
17
+ const pieces = splitCommand(command)
18
+
19
+ if (ENV_DUMP.test(command) || substitutions(command).some(each => touchesEnv(each, options)))
20
+ return pieces
21
+
22
+ const variables = variablesOf(command)
23
+
24
+ return pieces.filter((piece, index) => {
25
+ const { program, args } = parseCommand(piece.command)
26
+
27
+ if (readsEnv(piece, variables) || searchesEnv(program, args) || runnerReadsListedEnv(pieces, index, variables) || loopReadsListedEnv(pieces, index, variables))
28
+ return true
29
+
30
+ const isDump = dumpsContainerEnv(program, args) || dumpsEnvironment(program, args, tokenize(piece.command)) || (options.hasTrackedEnv === true && printsTrackedEnv(program, args))
31
+
32
+ if (!isDump)
33
+ return false
34
+
35
+ // a redact further down its pipeline masks what the command prints
36
+ for (let at = index; pieces[at]?.separator === '|'; at++) {
37
+ if (parseCommand(pieces[at + 1]?.command ?? '').program === 'redact')
38
+ return false
39
+ }
40
+
41
+ return true
42
+ })
43
+ }
44
+
45
+ // True when the command would read, write or print an env file or the whole environment; an env file named only inside a quoted message or a heredoc body is text, and a container's environment piped through `redact` is masked.
46
+ export function touchesEnv(command: string, options: { hasTrackedEnv?: boolean } = {}): boolean {
47
+ return touchingPieces(command, options).length > 0
48
+ }
49
+
50
+ export { isEnvFile, reachesEnvFile } from './guard-paths'
51
+ export { isSearchCommand } from './guard-search'