PRD: Turn Hacktools Inventory into the Install Authority

[mswell]

Problem Statement

Hacktools inventory is meant to be the structured definition of bug bounty tools, ProjectDiscovery tools, Go installs, Python installs, repository installs, wordlists, required paths, and post-install actions. Today, the data arrays, dry-run plan, installer loops, post-install behavior, and tests know overlapping but different parts of that model. This causes low locality and creates drift risk.

From the user's perspective, installing hacktools should be inspectable before execution and reliable during execution. From the maintainer's perspective, adding or changing a tool should happen in one inventory module, not across planning, installation, and tests.

Solution

Deepen the hacktools inventory module into the install authority. The inventory should describe tool records and post-install actions once, then expose a small interface for planning, applying, and validating. Host and network operations should sit behind adapters so tests can verify behavior without installing tools or cloning repositories.

The preferred seam is the existing hacktools inventory seam. The installer script should become a caller of that deeper module rather than a second implementation of the inventory model.

User Stories

1. As a bug bounty hunter, I want to preview all hacktools installation actions, so that I understand what will be installed.
2. As a bug bounty hunter, I want the install plan to match real install behavior, so that dry-run output is trustworthy.
3. As a bug bounty hunter, I want already-installed tools to be skipped safely, so that re-running installation is practical.
4. As a bug bounty hunter, I want wordlists to download to the configured list path, so that recon functions find their inputs.
5. As a bug bounty hunter, I want repository tools to clone or update predictably, so that tool state remains current.
6. As a bug bounty hunter, I want post-install actions to be part of the plan, so that generated templates and wordlists are not surprising.
7. As a maintainer, I want one hacktools inventory model, so that adding a tool has locality.
8. As a maintainer, I want ProjectDiscovery tool installation to be represented consistently with other Go tools, so that the model is simple.
9. As a maintainer, I want Python, Go, repository, wordlist, and post-install actions to have explicit semantics, so that behavior is testable.
10. As a maintainer, I want path expansion to be handled inside the inventory module, so that callers do not duplicate environment rules.
11. As a maintainer, I want network operations behind adapters, so that tests do not hit the network.
12. As a maintainer, I want command execution behind adapters, so that tests do not install real tools.
13. As a maintainer, I want the installer script to read like orchestration, so that install details live in the inventory implementation.
14. As a maintainer, I want stale test expectations to disappear, so that tests follow the inventory model rather than historical implementation details.
15. As an agent, I want the hacktools inventory module to explain plan and apply behavior, so that AI navigation does not require reconstructing loops by hand.
16. As an agent, I want tests to cross the hacktools inventory seam, so that refactors preserve user-visible behavior.
17. As a contributor, I want adding a wordlist to require only an inventory record and maybe a post-install decision, so that change scope is small.
18. As a contributor, I want adding a repository tool to specify dependency behavior explicitly, so that install failures are predictable.
19. As a contributor, I want post-install actions to be named domain actions, so that they can be planned, applied, and tested.
20. As a contributor, I want the deletion test to show that hacktools inventory earns its depth, so that deleting it would re-spread install complexity.
21. As a contributor, I want failure handling for clone, pull, build, and dependency steps to be consistent, so that partial tool failures are easier to diagnose.
22. As a contributor, I want dry-run output to be stable enough for review, so that plan changes are obvious in tests.

Implementation Decisions

• Keep hacktools inventory as the domain module for security tool installation definitions.
• Make the inventory module the source of truth for both plan and apply behavior.
• Use adapters for command lookup, command execution, downloads, repository operations, and filesystem writes.
• Preserve current tool sets unless a separate decision changes the inventory.
• Preserve configured path variables as the source of path values.
• Treat post-install actions as first-class inventory actions.
• Keep the installer script as a thin caller of the hacktools inventory interface.
• Avoid exposing implementation loops as the public interface.
• Use the deletion test to reject shallow extraction that only renames existing loops.

Testing Decisions

• Good tests should verify external behavior through the hacktools inventory interface: plan generation, path expansion, action ordering, skip decisions, and post-install declarations.
• Existing shell module tests are prior art and should be corrected and extended.
• Tests should not run real network downloads, real repository clones, or real tool installations.
• Tests should use fake adapters for command execution and filesystem behavior where needed.
• Tests should prove that dry-run and apply share one inventory model.
• Tests should include ProjectDiscovery tools, generic Go tools, Python tools, repository tools, wordlists, and post-install actions.
• Tests should verify that stale expectations, such as obsolete installer mechanisms, cannot pass unnoticed.

Out of Scope

• Changing the bug bounty tool list for product reasons.
• Replacing Go, Python, Git, or wordlist download mechanisms wholesale.
• Running live network integration tests by default.
• Changing the central path configuration model.
• Rewriting the installer in another language.
• Installing tools that are not already part of the inventory without separate approval.

Further Notes

This PRD is worth exploring because the inventory domain concept already exists and the current implementation shows drift between tests and behavior. The main value is locality: one inventory model should drive plan, apply, and validation.