Resolve operator paths against the CWD, making uv tool install usable

[bandrel]

Why

PR #42 made SpooNMAP installable — uv tool install git+https://github.com/trustedsec/spoonmap builds a self-contained wheel and resolves all 19 bundled NSE scripts from the isolated tool venv. But the installed tool was not yet usable, because spoonmap.py derived its operator directory from the module's own location:

dir_path = os.path.dirname(os.path.realpath(__file__))

Under uv tool install that is ~/.local/share/uv/tools/spoonmap/lib/python3.12/site-packages. And dir_path decided where config.json was read from, where exclusions.txt defaulted to, and — by default — where scan output was written. So an installed spoonmap wanted its config inside uv's managed tool environment and wrote engagement results there, into a directory that gets rebuilt whenever an upgrade installs a new version.

The root cause is that dir_path conflated where the program lives with where the operator's data lives. Those are the same directory in a checkout, which is why it went unnoticed. PR #42 already split out the program-data half (bundled NSE scripts moved to _NSE_DIR); this finishes the job.

What changed

Operator paths now resolve against the current working directory, via a single _operator_dir() helper. That covers config.json, exclusions.txt, the default output location, relative target_file / output_path / exclusions_file values inside config.json, and --cleanup.

The derivation was extracted out of main() deliberately: main() carries # pragma: no cover, so the one line that mattered was the one line no test could reach. It is now a tested helper.

_DIR and _NSE_DIR are untouched — bundled NSE scripts ship inside the wheel and must keep resolving from the module's location, or script_scan breaks on an installed tool. The __file__ anchor count went from two to one: the operator path no longer has any module anchor at all.

Also fixed: the two config-error messages printed a bare config.json.sample filename, which is unactionable for an installed user whose copy sits next to the module. They now print the resolved path.

No packaging or CI changes. pyproject.toml's only edit is a comment this branch falsified.

Verification

Proven against a real installed wheel rather than argued from source.

Runs from any directory, output stays local. Two unrelated directories, each with its own config.json ({"output_path": "results"}) and prior output:

$ cd engagement-a && spoonmap --cleanup
Scan data removed from .../engagement-a/results

$ ls engagement-b/results
all_live_hosts.txt   discovery      # untouched

Config loading follows the CWD. _load_config on the installed wheel, from an arbitrary directory:

_operator_dir() : .../engagement
  target_file      -> .../engagement/ranges.txt
  output_path      -> .../engagement/out
  exclusions_file  -> .../engagement/excl.txt
module lives at : .../v/lib/python3.12/site-packages
any resolved path inside the module dir? False

Nothing writes to _DIR: its only remaining uses are the NSE anchor, the two config.json.sample messages, and a docstring. Every os.makedirs sits under output_path.

Gate: 978 passed, 5 skipped, 100% coverage (floor 95%) · ruff clean · uv lock --check unaffected · bandit 32 baseline / 0 new. No suppressions, coverage floor untouched.

Behaviour change

Invoking by absolute path from elsewhere (cd /tmp && /opt/spoonmap/spoonmap.py) previously read /opt/spoonmap/config.json and wrote output under /opt/spoonmap/. It now uses /tmp. For the documented invocation — from inside the checkout — nothing changes, because the CWD and the checkout are the same directory.

This is disclosed in the README's new "Where Files Live" section, with a pointer from "Usage" so someone reads it before running rather than after wondering where their output went.

Docs

• README gains an ## Installation section covering uv tool install git+... and uv tool upgrade, stating plainly that no PyPI package exists, and noting that installing does not remove the need for masscan and nmap.
• README gains ## Where Files Live, documenting the CWD rule, the behaviour change, and the one exception — bundled NSE scripts, named in both forms (nse/ in a checkout, spoonmap_nse/ installed) so a reader can match it to what they have on disk.
• CLAUDE.md gains ## Operator Path Resolution covering the same semantics and the _DIR/_NSE_DIR boundary.

🤖 Generated with Claude Code