bash-write-targets 0.1.0__tar.gz

bash_write_targets-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hao li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bash_write_targets-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: bash-write-targets
+Version: 0.1.0
+Summary: Statically list the file-write targets of a bash command (redirects, tee, -o flags, cp/mv destinations)
+Author: hao li
+License: MIT
+Project-URL: Homepage, https://github.com/hahahahahahahahah6/bash-write-targets
+Keywords: bash,shell,static-analysis,security,ai-agents,audit
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# bash-write-targets
+
+Give it a bash command string; get back the list of files it may write to —
+before anything runs.
+
+```bash
+$ targets 'make 2>&1 | tee build.log; curl -s -o app.tar.gz https://example.com/app'
+build.log
+app.tar.gz
+```
+
+Stdlib-only. Static analysis — the command is **never executed**.
+
+## Why
+
+AI coding agents run a lot of bash. Before a command executes, an auditor
+(like a PreToolUse hook) wants to know: *which files could this touch?*
+Grepping for `>` misses `tee`, `curl -o`, `sed -i`, `dd of=`, `cp`/`mv`
+destinations, and writes hidden inside `$(...)`.
+
+`bash-write-targets` answers that one question, for one command, with no
+dependencies.
+
+## Install
+
+```bash
+pip install bash-write-targets
+```
+
+Requires Python 3.9+.
+
+## Usage
+
+```bash
+targets '<bash command>'        # one target per line
+targets --json '<bash command>' # JSON array, for hooks and scripts
+```
+
+Examples:
+
+```bash
+$ targets 'echo hello > out.txt'
+out.txt
+
+$ targets 'cat > note.txt <<EOF
+hello > world
+EOF'
+note.txt
+
+$ targets 'grep -r foo . | sort -o sorted.txt; mv sorted.txt final.txt'
+sorted.txt
+final.txt
+
+$ targets 'sed -i "s/a/b/g" config.ini && dd if=/dev/zero of=disk.img bs=1M count=1'
+config.ini
+disk.img
+```
+
+Covered: `>` `>>` `>|` `&>` `&>>` `2>` `2>>` `<>`, heredocs (bodies are
+stripped, not parsed), `$(...)` and backticks (scanned recursively), `tee`
+(including `-a`), `cp`/`mv`/`install` destinations, `sed -i`, `dd of=`,
+`truncate`, `touch`, `shred`, `zip` archives, and `-o`/`--output`-style
+flags for `curl`, `wget`, `gcc`/`cc`/`g++`/`clang`, `sort`, `pandoc`,
+`psql`, and `tar -f`.
+
+Deliberately skipped (not guessed at): `/dev/null`, fd duplications
+(`2>&1`), unresolvable `$VAR` expansions, bare globs, and input-side `<`
+redirections.
+
+## Differentiation
+
+This project exists because
+[agent-guard](https://github.com/hahahahahahahahah6/agent-guard) says so —
+literally. Its README's *Honest limitations* section documents the
+situation:
+
+> **Bash write-target extraction is static and approximate.** It is
+> shlex-based, so heavy quoting, `eval`, command substitution building
+> paths at runtime, and `python3 -c "open(...).write(...)"` are known gaps
+> — the target list is conservative by design (a missed target is a miss,
+> never a crash). ... **This is the documented frontier for a future
+> version, not a finished parser.**
+
+`bash-write-targets` is that future version, as a standalone tool:
+
+- **Deeper than the inline heuristic.** agent-guard's hook extracts
+  targets inline with a shallow shlex pass, good enough for a hot-path
+  block decision. This package goes further: heredoc-aware stripping,
+  recursive command-substitution scanning, and command-aware operand
+  parsing (`tee`, `sed -i` script-vs-file disambiguation, `cp -t`,
+  `--output=` forms).
+- **Reusable anywhere.** A PreToolUse hook, a CI audit step, or a human
+  double-checking a pasted command — one `targets` call, one line per
+  file, plus `--json` for machines.
+- **Safe by construction.** Pure static parsing over the command string.
+  Nothing is executed, no subshell is spawned, no file is touched —
+  auditing a destructive command cannot itself be destructive.
+
+## Honest limitations
+
+- Static, not proof. `eval`, paths assembled at runtime, and
+  `python3 -c "open(p).write(x)"` are known gaps — the list is
+  conservative by design.
+- `$VAR` and bare globs are skipped rather than resolved.
+- Network sinks (e.g. `curl --data` POSTing somewhere) are out of scope:
+  this tool lists *file* write targets.
+- A missed target is a miss, never a crash: malformed input yields fewer
+  results, not an exception.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

bash_write_targets-0.1.0/README.md

@@ -0,0 +1,112 @@
+# bash-write-targets
+
+Give it a bash command string; get back the list of files it may write to —
+before anything runs.
+
+```bash
+$ targets 'make 2>&1 | tee build.log; curl -s -o app.tar.gz https://example.com/app'
+build.log
+app.tar.gz
+```
+
+Stdlib-only. Static analysis — the command is **never executed**.
+
+## Why
+
+AI coding agents run a lot of bash. Before a command executes, an auditor
+(like a PreToolUse hook) wants to know: *which files could this touch?*
+Grepping for `>` misses `tee`, `curl -o`, `sed -i`, `dd of=`, `cp`/`mv`
+destinations, and writes hidden inside `$(...)`.
+
+`bash-write-targets` answers that one question, for one command, with no
+dependencies.
+
+## Install
+
+```bash
+pip install bash-write-targets
+```
+
+Requires Python 3.9+.
+
+## Usage
+
+```bash
+targets '<bash command>'        # one target per line
+targets --json '<bash command>' # JSON array, for hooks and scripts
+```
+
+Examples:
+
+```bash
+$ targets 'echo hello > out.txt'
+out.txt
+
+$ targets 'cat > note.txt <<EOF
+hello > world
+EOF'
+note.txt
+
+$ targets 'grep -r foo . | sort -o sorted.txt; mv sorted.txt final.txt'
+sorted.txt
+final.txt
+
+$ targets 'sed -i "s/a/b/g" config.ini && dd if=/dev/zero of=disk.img bs=1M count=1'
+config.ini
+disk.img
+```
+
+Covered: `>` `>>` `>|` `&>` `&>>` `2>` `2>>` `<>`, heredocs (bodies are
+stripped, not parsed), `$(...)` and backticks (scanned recursively), `tee`
+(including `-a`), `cp`/`mv`/`install` destinations, `sed -i`, `dd of=`,
+`truncate`, `touch`, `shred`, `zip` archives, and `-o`/`--output`-style
+flags for `curl`, `wget`, `gcc`/`cc`/`g++`/`clang`, `sort`, `pandoc`,
+`psql`, and `tar -f`.
+
+Deliberately skipped (not guessed at): `/dev/null`, fd duplications
+(`2>&1`), unresolvable `$VAR` expansions, bare globs, and input-side `<`
+redirections.
+
+## Differentiation
+
+This project exists because
+[agent-guard](https://github.com/hahahahahahahahah6/agent-guard) says so —
+literally. Its README's *Honest limitations* section documents the
+situation:
+
+> **Bash write-target extraction is static and approximate.** It is
+> shlex-based, so heavy quoting, `eval`, command substitution building
+> paths at runtime, and `python3 -c "open(...).write(...)"` are known gaps
+> — the target list is conservative by design (a missed target is a miss,
+> never a crash). ... **This is the documented frontier for a future
+> version, not a finished parser.**
+
+`bash-write-targets` is that future version, as a standalone tool:
+
+- **Deeper than the inline heuristic.** agent-guard's hook extracts
+  targets inline with a shallow shlex pass, good enough for a hot-path
+  block decision. This package goes further: heredoc-aware stripping,
+  recursive command-substitution scanning, and command-aware operand
+  parsing (`tee`, `sed -i` script-vs-file disambiguation, `cp -t`,
+  `--output=` forms).
+- **Reusable anywhere.** A PreToolUse hook, a CI audit step, or a human
+  double-checking a pasted command — one `targets` call, one line per
+  file, plus `--json` for machines.
+- **Safe by construction.** Pure static parsing over the command string.
+  Nothing is executed, no subshell is spawned, no file is touched —
+  auditing a destructive command cannot itself be destructive.
+
+## Honest limitations
+
+- Static, not proof. `eval`, paths assembled at runtime, and
+  `python3 -c "open(p).write(x)"` are known gaps — the list is
+  conservative by design.
+- `$VAR` and bare globs are skipped rather than resolved.
+- Network sinks (e.g. `curl --data` POSTing somewhere) are out of scope:
+  this tool lists *file* write targets.
+- A missed target is a miss, never a crash: malformed input yields fewer
+  results, not an exception.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

bash_write_targets-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bash-write-targets"
+version = "0.1.0"
+description = "Statically list the file-write targets of a bash command (redirects, tee, -o flags, cp/mv destinations)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "hao li" }]
+keywords = ["bash", "shell", "static-analysis", "security", "ai-agents", "audit"]
+
+[project.scripts]
+targets = "bash_write_targets.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/hahahahahahahahah6/bash-write-targets"
+
+[tool.setuptools.packages.find]
+where = ["src"]

bash_write_targets-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bash_write_targets-0.1.0/src/bash_write_targets/__init__.py

@@ -0,0 +1,3 @@
+"""bash-write-targets: statically list the files a bash command may write to."""
+
+__version__ = "0.1.0"

bash_write_targets-0.1.0/src/bash_write_targets/cli.py

@@ -0,0 +1,39 @@
+"""CLI: targets '<bash command>' -> list the files the command may write to."""
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .extract import extract
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="targets",
+        description=(
+            "Statically list the file-write targets of a bash command "
+            "(redirections, tee, -o/--output flags, cp/mv destinations, ...). "
+            "The command is never executed."
+        ),
+    )
+    parser.add_argument("command", help="bash command string to audit")
+    parser.add_argument(
+        "--json", action="store_true", help="print targets as a JSON array"
+    )
+    parser.add_argument(
+        "--version", action="version", version="%(prog)s " + __version__
+    )
+    args = parser.parse_args(argv)
+
+    targets = extract(args.command)
+    if args.json:
+        print(json.dumps(targets))
+    else:
+        for t in targets:
+            print(t)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

bash_write_targets-0.1.0/src/bash_write_targets/extract.py

@@ -0,0 +1,340 @@
+"""Static extraction of file-write targets from a bash command string.
+
+Never executes anything. Conservative by design: a missed target is a miss,
+never a crash.
+
+Covered:
+  * redirections:  >, >>, >|, &>, &>>, 2>, 2>>, <>
+  * heredocs (<<EOF): bodies are stripped so their contents are not mistaken
+    for targets
+  * command substitution: $(...) and `...` are scanned recursively
+  * tee (all operands, -a/--append aware)
+  * cp / mv / install (destination operand; --target-directory aware)
+  * sed -i (in-place operands)
+  * dd of=FILE, truncate, touch, shred, zip (archive operand)
+  * -o / --output style flags for curl, wget, gcc/cc/g++/clang, sort,
+    pandoc, psql, tar -f/--file
+
+Known gaps (documented, not guessed at):
+  * eval and paths built at runtime
+  * unresolvable $VAR expansions (skipped, not guessed)
+  * bare globs (skipped)
+  * /dev/null (skipped)
+  * python3 -c "open(...).write(...)" style embedded writes
+  * network sinks (e.g. curl --data posting to a URL)
+"""
+
+import re
+import shlex
+
+_SEPARATORS = {"|", "||", "&", "&&", ";", "(", ")", "\n"}
+_PREFIX_COMMANDS = {"sudo", "env", "command", "time", "nohup"}
+
+_FD_WORD = re.compile(r"^&?\d+$")
+_ASSIGN_WORD = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=.*$")
+_DD_OF = re.compile(r"^of=(.+)$")
+_GLOB_CHARS = re.compile(r"[*?\[]")
+_VAR_CHARS = re.compile(r"[$]")
+
+# command -> output flags whose next token (or --flag=value) names a file
+KNOWN_OUTPUT_FLAGS = {
+    "curl": ("-o", "--output"),
+    "wget": ("-O", "--output-document"),
+    "gcc": ("-o",),
+    "cc": ("-o",),
+    "g++": ("-o",),
+    "clang": ("-o",),
+    "clang++": ("-o",),
+    "sort": ("-o", "--output"),
+    "pandoc": ("-o", "--output"),
+    "psql": ("-o", "--output"),
+    "tar": ("-f", "--file"),
+}
+
+
+def _valid_target(word):
+    """Decide whether a candidate word is a plausible file path."""
+    if not word:
+        return False
+    if word == "/dev/null":
+        return False
+    if word == "-":  # stdout/stdin placeholder
+        return False
+    if _FD_WORD.match(word):
+        return False
+    if _VAR_CHARS.search(word):
+        return False  # unresolvable at static time; skip, don't guess
+    if _GLOB_CHARS.search(word):
+        return False  # bare globs are ambiguous; skip, don't guess
+    return True
+
+
+def _strip_heredocs(text):
+    """Remove heredoc bodies so their contents are not parsed as commands."""
+    pattern = re.compile(r"<<-?[ \t]*(?P<q>['\"]?)(?P<word>[A-Za-z0-9_]+)(?P=q)")
+    out = text
+    while True:
+        m = pattern.search(out)
+        if not m:
+            return out
+        word = m.group("word")
+        term = re.compile(r"^" + re.escape(word) + r"[ \t]*$", re.M)
+        tm = term.search(out, m.end())
+        end = tm.end() if tm else len(out)
+        out = out[: m.start()] + " " + out[end:]
+
+
+def _extract_substitutions(text):
+    """Pull out $(...) and `...` spans; return (outer_text, [inner, ...])."""
+    inners = []
+    out = []
+    i, n = 0, len(text)
+    while i < n:
+        if text.startswith("$(", i):
+            depth, j = 1, i + 2
+            in_single = in_double = False
+            while j < n and depth:
+                c = text[j]
+                if in_single:
+                    if c == "'":
+                        in_single = False
+                elif in_double:
+                    if c == '"':
+                        in_double = False
+                    elif c == "\\":
+                        j += 1
+                else:
+                    if c == "'":
+                        in_single = True
+                    elif c == '"':
+                        in_double = True
+                    elif c == "(":
+                        depth += 1
+                    elif c == ")":
+                        depth -= 1
+                j += 1
+            if depth == 0:
+                inners.append(text[i + 2 : j - 1])
+                out.append(" ")
+                i = j
+            else:  # unbalanced; keep scanning char by char
+                out.append(text[i])
+                i += 1
+        elif text[i] == "`":
+            j = i + 1
+            while j < n and text[j] != "`":
+                if text[j] == "\\":
+                    j += 1
+                j += 1
+            if j < n:
+                inners.append(text[i + 1 : j])
+                out.append(" ")
+                i = j + 1
+            else:
+                out.append(text[i])
+                i += 1
+        else:
+            out.append(text[i])
+            i += 1
+    return "".join(out), inners
+
+
+def _tokenize(text):
+    """shlex tokenize with shell punctuation kept as separate tokens."""
+    try:
+        lexer = shlex.shlex(text, posix=True, punctuation_chars="|&;()<>\n")
+    except TypeError:  # very old Python without punctuation_chars
+        lexer = shlex.shlex(text, posix=True)
+    lexer.whitespace_split = True
+    raw = list(lexer)
+    # merge doubled punctuation chars: >>, <<, &&, ||
+    merged = []
+    for tok in raw:
+        if merged and tok in (">", "<", "&", "|") and merged[-1] == tok:
+            merged[-1] = tok * 2
+        else:
+            merged.append(tok)
+    return merged
+
+
+def _redir_op(tok):
+    """Normalize a token to a redirection operator, or None.
+
+    Leading fd digits are stripped: '2>' -> '>'.
+    """
+    m = re.match(r"^(\d*)(>>?|<<-?|>&|&>>?|>\||<>)$", tok)
+    if not m:
+        return None
+    return m.group(2)
+
+
+def _scan_tokens(tokens, add):
+    i, n = 0, len(tokens)
+    at_start = True
+    cmd = None
+    flags = []
+    operands = []
+    pending_value = None  # flag waiting for its value (name, kind)
+    target_dir = None
+
+    def finish_segment():
+        nonlocal cmd, flags, operands, pending_value, target_dir
+        if cmd == "tee":
+            for op in operands:
+                add(op)
+        elif cmd in ("cp", "mv", "install"):
+            if target_dir is not None:
+                add(target_dir)
+            elif len(operands) >= 2:
+                add(operands[-1])
+        elif cmd == "sed":
+            if any(
+                f == "-i" or f.startswith("-i") or f == "--in-place"
+                for f in flags
+            ):
+                files = operands
+                # without -e/-f the first operand is the sed script, not a file
+                if files and not any(
+                    f == "-e" or f == "-f" or f.startswith("-e") or f.startswith("--expression")
+                    for f in flags
+                ):
+                    files = files[1:]
+                for op in files:
+                    add(op)
+        elif cmd == "dd":
+            for t in operands + flags:
+                m = _DD_OF.match(t)
+                if m:
+                    add(m.group(1))
+        elif cmd in ("truncate", "touch", "shred"):
+            for op in operands:
+                add(op)
+        elif cmd == "zip":
+            if operands:
+                add(operands[0])
+        cmd, flags, operands, pending_value, target_dir = (
+            None, [], [], None, None,
+        )
+
+    def consume_flag_value():
+        nonlocal i, pending_value, target_dir
+        name, kind = pending_value
+        pending_value = None
+        if i < n and tokens[i] not in _SEPARATORS and _redir_op(tokens[i]) is None:
+            if kind == "output":
+                add(tokens[i])
+            elif kind == "targetdir":
+                target_dir = tokens[i]
+            # kind == "skip" (e.g. truncate -s): value consumed, not a target
+            i += 1
+
+    while i < n:
+        tok = tokens[i]
+
+        if pending_value is not None:
+            consume_flag_value()
+            continue
+
+        if tok in _SEPARATORS:
+            finish_segment()
+            at_start = True
+            i += 1
+            continue
+
+        op = _redir_op(tok)
+        if op is not None:
+            nxt = tokens[i + 1] if i + 1 < n else None
+            if op in ("<<", "<<-"):
+                i += 2  # heredoc bodies already stripped; skip delimiter
+                continue
+            if op == "<":
+                i += 2 if nxt not in (None, "(") else 1  # input side, not a target
+                continue
+            # output redirections: >, >>, >|, &>, &>>, <>
+            if nxt == "(":
+                i += 1  # process substitution >(...); not a file target
+                continue
+            if nxt == "&":
+                # >&2 / 2>&1 style fd duplication; only a real path counts
+                tgt = tokens[i + 2] if i + 2 < n else None
+                if (
+                    tgt is not None
+                    and tgt not in _SEPARATORS
+                    and _redir_op(tgt) is None
+                    and not _FD_WORD.match(tgt)
+                ):
+                    add(tgt)
+                i += 3
+                continue
+            if nxt is None or nxt in _SEPARATORS or _redir_op(nxt) is not None:
+                i += 1  # malformed; skip
+                continue
+            add(nxt)
+            i += 2
+            continue
+
+        if at_start:
+            if _ASSIGN_WORD.match(tok):
+                i += 1  # FOO=bar env assignment
+                continue
+            if tok in _PREFIX_COMMANDS:
+                i += 1
+                continue
+            cmd = tok.split("/")[-1]
+            at_start = False
+            i += 1
+            continue
+
+        # operand / flag position for the current command
+        if tok.startswith("-") and tok != "-":
+            flags.append(tok)
+            if cmd in KNOWN_OUTPUT_FLAGS and tok in KNOWN_OUTPUT_FLAGS[cmd]:
+                if "=" in tok:
+                    _, _, value = tok.partition("=")
+                    add(value)
+                else:
+                    pending_value = (tok, "output")
+            elif "=" in tok and tok.split("=", 1)[0] in (
+                "--target-directory",
+                "--output",
+                "--file",
+                "--output-document",
+            ):
+                _, _, value = tok.partition("=")
+                if tok.startswith("--target-directory"):
+                    target_dir = value
+                else:
+                    add(value)
+            elif cmd == "truncate" and tok in ("-s", "--size"):
+                pending_value = (tok, "skip")
+            elif cmd in ("cp", "mv", "install") and tok in ("-t", "--target-directory"):
+                pending_value = (tok, "targetdir")
+            i += 1
+            continue
+
+        if _ASSIGN_WORD.match(tok) and cmd != "dd":
+            i += 1  # VAR=x in operand position is not a file
+            continue
+        operands.append(tok)
+        i += 1
+
+    finish_segment()
+
+
+def extract(command):
+    """Return the ordered, deduplicated list of files the command may write.
+
+    Pure static analysis; the command is never executed.
+    """
+    targets = []
+
+    def add(word):
+        if _valid_target(word) and word not in targets:
+            targets.append(word)
+
+    outer, inners = _extract_substitutions(_strip_heredocs(command))
+    for inner in inners:
+        for t in extract(inner):
+            add(t)
+    _scan_tokens(_tokenize(outer), add)
+    return targets

bash_write_targets-0.1.0/src/bash_write_targets.egg-info/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: bash-write-targets
+Version: 0.1.0
+Summary: Statically list the file-write targets of a bash command (redirects, tee, -o flags, cp/mv destinations)
+Author: hao li
+License: MIT
+Project-URL: Homepage, https://github.com/hahahahahahahahah6/bash-write-targets
+Keywords: bash,shell,static-analysis,security,ai-agents,audit
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# bash-write-targets
+
+Give it a bash command string; get back the list of files it may write to —
+before anything runs.
+
+```bash
+$ targets 'make 2>&1 | tee build.log; curl -s -o app.tar.gz https://example.com/app'
+build.log
+app.tar.gz
+```
+
+Stdlib-only. Static analysis — the command is **never executed**.
+
+## Why
+
+AI coding agents run a lot of bash. Before a command executes, an auditor
+(like a PreToolUse hook) wants to know: *which files could this touch?*
+Grepping for `>` misses `tee`, `curl -o`, `sed -i`, `dd of=`, `cp`/`mv`
+destinations, and writes hidden inside `$(...)`.
+
+`bash-write-targets` answers that one question, for one command, with no
+dependencies.
+
+## Install
+
+```bash
+pip install bash-write-targets
+```
+
+Requires Python 3.9+.
+
+## Usage
+
+```bash
+targets '<bash command>'        # one target per line
+targets --json '<bash command>' # JSON array, for hooks and scripts
+```
+
+Examples:
+
+```bash
+$ targets 'echo hello > out.txt'
+out.txt
+
+$ targets 'cat > note.txt <<EOF
+hello > world
+EOF'
+note.txt
+
+$ targets 'grep -r foo . | sort -o sorted.txt; mv sorted.txt final.txt'
+sorted.txt
+final.txt
+
+$ targets 'sed -i "s/a/b/g" config.ini && dd if=/dev/zero of=disk.img bs=1M count=1'
+config.ini
+disk.img
+```
+
+Covered: `>` `>>` `>|` `&>` `&>>` `2>` `2>>` `<>`, heredocs (bodies are
+stripped, not parsed), `$(...)` and backticks (scanned recursively), `tee`
+(including `-a`), `cp`/`mv`/`install` destinations, `sed -i`, `dd of=`,
+`truncate`, `touch`, `shred`, `zip` archives, and `-o`/`--output`-style
+flags for `curl`, `wget`, `gcc`/`cc`/`g++`/`clang`, `sort`, `pandoc`,
+`psql`, and `tar -f`.
+
+Deliberately skipped (not guessed at): `/dev/null`, fd duplications
+(`2>&1`), unresolvable `$VAR` expansions, bare globs, and input-side `<`
+redirections.
+
+## Differentiation
+
+This project exists because
+[agent-guard](https://github.com/hahahahahahahahah6/agent-guard) says so —
+literally. Its README's *Honest limitations* section documents the
+situation:
+
+> **Bash write-target extraction is static and approximate.** It is
+> shlex-based, so heavy quoting, `eval`, command substitution building
+> paths at runtime, and `python3 -c "open(...).write(...)"` are known gaps
+> — the target list is conservative by design (a missed target is a miss,
+> never a crash). ... **This is the documented frontier for a future
+> version, not a finished parser.**
+
+`bash-write-targets` is that future version, as a standalone tool:
+
+- **Deeper than the inline heuristic.** agent-guard's hook extracts
+  targets inline with a shallow shlex pass, good enough for a hot-path
+  block decision. This package goes further: heredoc-aware stripping,
+  recursive command-substitution scanning, and command-aware operand
+  parsing (`tee`, `sed -i` script-vs-file disambiguation, `cp -t`,
+  `--output=` forms).
+- **Reusable anywhere.** A PreToolUse hook, a CI audit step, or a human
+  double-checking a pasted command — one `targets` call, one line per
+  file, plus `--json` for machines.
+- **Safe by construction.** Pure static parsing over the command string.
+  Nothing is executed, no subshell is spawned, no file is touched —
+  auditing a destructive command cannot itself be destructive.
+
+## Honest limitations
+
+- Static, not proof. `eval`, paths assembled at runtime, and
+  `python3 -c "open(p).write(x)"` are known gaps — the list is
+  conservative by design.
+- `$VAR` and bare globs are skipped rather than resolved.
+- Network sinks (e.g. `curl --data` POSTing somewhere) are out of scope:
+  this tool lists *file* write targets.
+- A missed target is a miss, never a crash: malformed input yields fewer
+  results, not an exception.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

bash_write_targets-0.1.0/src/bash_write_targets.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/bash_write_targets/__init__.py
+src/bash_write_targets/cli.py
+src/bash_write_targets/extract.py
+src/bash_write_targets.egg-info/PKG-INFO
+src/bash_write_targets.egg-info/SOURCES.txt
+src/bash_write_targets.egg-info/dependency_links.txt
+src/bash_write_targets.egg-info/entry_points.txt
+src/bash_write_targets.egg-info/top_level.txt
+tests/test_targets.py

bash_write_targets-0.1.0/src/bash_write_targets.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bash_write_targets-0.1.0/src/bash_write_targets.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+targets = bash_write_targets.cli:main

bash_write_targets-0.1.0/src/bash_write_targets.egg-info/top_level.txt

@@ -0,0 +1 @@
+bash_write_targets

bash_write_targets-0.1.0/tests/test_targets.py

@@ -0,0 +1,138 @@
+"""Smoke tests for bash-write-targets. Run: python3 tests/test_targets.py"""
+
+import io
+import json
+import os
+import sys
+from contextlib import redirect_stdout
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from bash_write_targets import cli  # noqa: E402
+from bash_write_targets.extract import extract  # noqa: E402
+
+
+def check(name, command, expected):
+    got = extract(command)
+    assert got == expected, f"{name}: for {command!r} got {got!r}, want {expected!r}"
+
+
+def test_simple_redirect():
+    check("redirect", "echo hello > out.txt", ["out.txt"])
+
+
+def test_append_redirect():
+    check("append", "echo hello >> log.txt", ["log.txt"])
+
+
+def test_stderr_redirect():
+    check("stderr", "cmd 2> err.log", ["err.log"])
+
+
+def test_combined_redirect():
+    check("combined", "cmd &> all.log", ["all.log"])
+
+
+def test_fd_duplication_skipped():
+    check("fddup", "cmd > out.txt 2>&1", ["out.txt"])
+    check("fddup2", "cmd >&2", [])
+
+
+def test_dev_null_skipped():
+    check("devnull", "cmd > /dev/null 2>&1", [])
+
+
+def test_tee():
+    check("tee", "make 2>&1 | tee build.log", ["build.log"])
+    check("tee-multi", "cmd | tee -a a.log b.log", ["a.log", "b.log"])
+
+
+def test_output_flags():
+    check("curl-o", "curl -s -o page.html https://example.com", ["page.html"])
+    check("curl-long", "curl --output=dl.bin https://example.com/x", ["dl.bin"])
+    check("wget", "wget -O data.zip https://example.com/d", ["data.zip"])
+    check("gcc", "gcc -O2 -o app main.c", ["app"])
+
+
+def test_copy_move():
+    check("cp", "cp -r src/ dst/", ["dst/"])
+    check("mv", "mv old.txt new.txt", ["new.txt"])
+
+
+def test_sed_inplace():
+    check("sed-i", "sed -i 's/a/b/' file.txt", ["file.txt"])
+
+
+def test_dd_truncate_touch():
+    check("dd", "dd if=/dev/zero of=disk.img bs=1M count=10", ["disk.img"])
+    check("truncate", "truncate -s 0 app.log", ["app.log"])
+    check("touch", "touch newfile.txt", ["newfile.txt"])
+
+
+def test_heredoc_body_not_parsed():
+    check(
+        "heredoc",
+        "cat > note.txt <<EOF\nsome > text >> here\nEOF",
+        ["note.txt"],
+    )
+
+
+def test_command_substitution_recursive():
+    check(
+        "subst",
+        "echo $(date > inner.txt) > outer.txt",
+        ["inner.txt", "outer.txt"],
+    )
+
+
+def test_var_and_glob_skipped():
+    check("var", "echo hi > $OUTFILE", [])
+    check("glob", "echo hi > *.log", [])
+
+
+def test_pipeline_segments():
+    check(
+        "pipeline",
+        "grep foo in.txt | sort -o sorted.txt; mv sorted.txt final.txt",
+        ["sorted.txt", "final.txt"],
+    )
+
+
+def test_quoted_filename():
+    check("quoted", 'echo x > "my file.txt"', ["my file.txt"])
+
+
+def test_no_writes():
+    check("nowrite", "ls -la | grep foo", [])
+
+
+def test_cli_text_output():
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        rc = cli.main(["echo hi > cli.txt"])
+    assert rc == 0
+    assert buf.getvalue().strip() == "cli.txt"
+
+
+def test_cli_json_output():
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        rc = cli.main(["--json", "cmd | tee j1.log j2.log"])
+    assert rc == 0
+    assert json.loads(buf.getvalue()) == ["j1.log", "j2.log"]
+
+
+if __name__ == "__main__":
+    tests = [
+        v for k, v in sorted(globals().items()) if k.startswith("test_")
+    ]
+    failed = 0
+    for t in tests:
+        try:
+            t()
+            print(f"PASS {t.__name__}")
+        except AssertionError as e:
+            failed += 1
+            print(f"FAIL {t.__name__}: {e}")
+    print(f"{len(tests) - failed}/{len(tests)} passed")
+    sys.exit(1 if failed else 0)