docs(08): create phase plan

2026-04-06 00:13:13 +03:00
parent 4c2081821f
commit 46cf55ad37
8 changed files with 1637 additions and 1 deletions
--- a/.planning/phases/08-dork-engine/08-06-PLAN.md
+++ b/.planning/phases/08-dork-engine/08-06-PLAN.md
@@ -0,0 +1,258 @@
+---
+phase: 08-dork-engine
+plan: 06
+type: execute
+wave: 3
+depends_on: [08-01, 08-02, 08-03, 08-04, 08-05]
+files_modified:
+  - cmd/dorks.go
+  - cmd/dorks_test.go
+  - cmd/stubs.go
+  - cmd/root.go
+autonomous: true
+requirements:
+  - DORK-03
+  - DORK-04
+must_haves:
+  truths:
+    - "`keyhunter dorks list` prints a table of embedded + custom dorks"
+    - "`keyhunter dorks list --source=github --category=frontier` filters correctly"
+    - "`keyhunter dorks info <id>` prints full dork detail"
+    - "`keyhunter dorks run --source=github --id=<id>` calls GitHubExecutor"
+    - "`keyhunter dorks run --source=shodan` returns ErrSourceNotImplemented with a helpful message"
+    - "`keyhunter dorks add --source=github --category=frontier --query=... --description=...` persists to custom_dorks table"
+    - "`keyhunter dorks delete <id>` removes from custom_dorks and refuses embedded IDs"
+    - "`keyhunter dorks export --format=yaml` dumps embedded+custom"
+  artifacts:
+    - path: "cmd/dorks.go"
+      provides: "dorks Cobra command tree replacing stub"
+      contains: "dorksCmd.AddCommand"
+  key_links:
+    - from: "cmd/dorks.go"
+      to: "pkg/dorks.Registry"
+      via: "dorks.NewRegistry()"
+      pattern: "dorks.NewRegistry"
+    - from: "cmd/dorks.go run"
+      to: "pkg/dorks.GitHubExecutor"
+      via: "NewGitHubExecutor(viper.GetString(\"dorks.github.token\"))"
+      pattern: "NewGitHubExecutor"
+    - from: "cmd/dorks.go add/delete"
+      to: "storage.DB custom_dorks CRUD"
+      via: "db.SaveCustomDork / DeleteCustomDork"
+      pattern: "SaveCustomDork|DeleteCustomDork"
+---
+
+<objective>
+Replace the Phase-8 dorks stub in cmd/stubs.go with a full Cobra command tree:
+list / run / add / export / info / delete. Wires the Registry (embedded dorks)
+together with storage custom_dorks (user dorks) and the GitHubExecutor (live
+execution). Satisfies DORK-03 (all four CLI verbs) and DORK-04 (category
+filtering via --category flag).
+
+Purpose: User-facing surface of the dork engine — everything built in 08-01
+through 08-05 becomes usable from the CLI.
+Output: Working `keyhunter dorks ...` subcommands.
+</objective>
+
+<execution_context>
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/phases/08-dork-engine/08-CONTEXT.md
+@.planning/phases/08-dork-engine/08-01-PLAN.md
+@.planning/phases/08-dork-engine/08-05-PLAN.md
+@cmd/stubs.go
+@cmd/root.go
+@cmd/keys.go
+@pkg/dorks/schema.go
+@pkg/dorks/registry.go
+@pkg/dorks/executor.go
+@pkg/storage/custom_dorks.go
+
+<interfaces>
+<!-- From prior plans -->
+```go
+// pkg/dorks
+func NewRegistry() (*Registry, error)
+func (r *Registry) List() []Dork
+func (r *Registry) Get(id string) (Dork, bool)
+func (r *Registry) ListBySource(src string) []Dork
+func (r *Registry) ListByCategory(cat string) []Dork
+func NewGitHubExecutor(token string) *GitHubExecutor
+
+// pkg/storage
+func (db *DB) SaveCustomDork(d CustomDork) (int64, error)
+func (db *DB) ListCustomDorks() ([]CustomDork, error)
+func (db *DB) GetCustomDorkByDorkID(dorkID string) (CustomDork, error)
+func (db *DB) DeleteCustomDork(id int64) (int64, error)
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: cmd/dorks.go command tree (list/info/export)</name>
+  <files>cmd/dorks.go, cmd/stubs.go, cmd/root.go</files>
+  <action>
+    1. Remove `var dorksCmd` from cmd/stubs.go (keep the rest of the stubs file
+       untouched).
+
+    2. Create cmd/dorks.go with the full command tree. Wire into root.go by
+       leaving the existing `rootCmd.AddCommand(dorksCmd)` in place — only the
+       declaration moves.
+
+    Structure:
+    ```go
+    package cmd
+
+    import (
+        "context"
+        "encoding/json"
+        "errors"
+        "fmt"
+        "os"
+        "strings"
+
+        "github.com/spf13/cobra"
+        "github.com/spf13/viper"
+        "gopkg.in/yaml.v3"
+
+        "github.com/<OWNER>/<REPO>/pkg/dorks"
+        "github.com/<OWNER>/<REPO>/pkg/storage"
+    )
+
+    var (
+        dorksFilterSource   string
+        dorksFilterCategory string
+        dorksRunID          string
+        dorksRunLimit       int
+        dorksAddSource      string
+        dorksAddCategory    string
+        dorksAddID          string
+        dorksAddName        string
+        dorksAddQuery       string
+        dorksAddDescription string
+        dorksExportFormat   string
+    )
+
+    var dorksCmd = &cobra.Command{
+        Use:   "dorks",
+        Short: "Manage and run dork queries (DORK-01..DORK-04)",
+    }
+
+    // list, info, run, add, delete, export subcommands declared here.
+    ```
+
+    Replace `<OWNER>/<REPO>` by reading the existing `module` line in
+    /home/salva/Documents/apikey/go.mod before writing the file (use the same
+    import path that cmd/keys.go uses).
+
+    **dorks list** — merges Registry.List() + db.ListCustomDorks(). Applies
+    --source and --category filters in memory. Prints a lipgloss table
+    (reuse pkg/output helpers if present, else a simple tab-aligned fmt). Mark
+    custom rows with a `*` prefix on the ID column.
+
+    **dorks info <id>** — looks up by dork_id first in Registry.Get, falls back
+    to db.GetCustomDorkByDorkID. Prints all fields including tags.
+
+    **dorks export [--format=yaml|json]** — emits a single combined list of
+    embedded + custom dorks in the requested format. Default yaml.
+
+    Use `initDorksDB()` helper that opens storage.DB using the same path logic
+    cmd/keys.go uses (viper.GetString("database.path")) so tests can inject a
+    temp path.
+  </action>
+  <verify>
+    <automated>cd /home/salva/Documents/apikey && go build ./... && go run ./ dorks list --source=github --category=frontier 2>&1 | grep -Ei '(openai|anthropic)'</automated>
+  </verify>
+  <done>
+    list/info/export commands compile and run. Filtering by source/category
+    works. Stub removed from cmd/stubs.go.
+  </done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 2: dorks run/add/delete + command tests</name>
+  <files>cmd/dorks.go, cmd/dorks_test.go</files>
+  <behavior>
+    - Test: `dorks add` persists a custom dork and `dorks list` shows it marked with `*`
+    - Test: `dorks delete <custom-id>` removes it; `dorks delete <embedded-id>` errors "embedded dorks cannot be deleted"
+    - Test: `dorks run --source=shodan --id=<shodan-id>` returns error wrapping ErrSourceNotImplemented
+    - Test: `dorks run --source=github --id=<id>` with empty GITHUB_TOKEN returns ErrMissingAuth setup message
+    - Test: `dorks run --source=github --id=<id>` with injected fake GitHubExecutor returns mocked matches
+    - Use cobra.Command.SetArgs + bytes.Buffer to capture stdout in tests; inject
+      a tempdir DB path via viper.Set("database.path", tmp).
+  </behavior>
+  <action>
+    1. Add **dorks add** subcommand to cmd/dorks.go. Builds a storage.CustomDork
+       from flags, validates source and category against dorks.ValidSources /
+       valid categories (frontier, specialized, infrastructure, emerging,
+       enterprise), calls db.SaveCustomDork. Fails if dork_id collides with an
+       embedded dork ID.
+
+    2. Add **dorks delete <dork-id>** subcommand. If the ID matches an embedded
+       dork, print "embedded dorks cannot be deleted" and exit 2. Otherwise
+       call db.GetCustomDorkByDorkID -> db.DeleteCustomDork.
+
+    3. Add **dorks run** subcommand:
+       - Required flags: --source; optional: --id, --category, --limit (default 10)
+       - If --id is set, run just that single dork (from registry or custom)
+       - Else, run all dorks matching --source and --category filters
+       - For each dork: dispatch via a Runner wired only with GitHub executor.
+         Non-github sources return fmt.Errorf wrapping ErrSourceNotImplemented
+         with message: "source %q not yet implemented (coming Phase 9-16)"
+       - Print matches as a simple list: `[dork-id] URL  (path)  snippet`
+       - Exit code 0 on success (even with zero matches), 2 on any executor
+         error other than ErrSourceNotImplemented (which should exit 2 also
+         but with the friendly message).
+
+    4. Extract the executor factory into a package-level var so tests can inject:
+       ```go
+       var newGitHubExecutor = func() dorks.Executor {
+           return dorks.NewGitHubExecutor(viper.GetString("dorks.github.token"))
+       }
+       ```
+       Tests override `newGitHubExecutor` to return a fake Executor.
+
+    5. Create cmd/dorks_test.go:
+       - Helper `setupDorksTest(t)` — creates tempdir, viper.Set("database.path", ...),
+         opens DB via initDorksDB, runs schema, returns cleanup func.
+       - Tests execute rootCmd with SetArgs([]string{"dorks", "add", "--source=github", ...}).
+       - Capture output via rootCmd.SetOut(&buf).
+       - FakeExecutor type implements dorks.Executor with a stubbed Execute()
+         returning canned Match slice.
+
+    6. **Config binding:** In cmd/root.go initConfig, ensure
+       `viper.BindEnv("dorks.github.token", "GITHUB_TOKEN")` is set so the
+       executor picks up the env var.
+  </action>
+  <verify>
+    <automated>cd /home/salva/Documents/apikey && go test ./cmd/... -run Dorks -v</automated>
+  </verify>
+  <done>
+    run/add/delete subcommands work end-to-end. All cmd/dorks_test.go tests pass.
+    GITHUB_TOKEN env var bound. Embedded dork deletion refused.
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+- `go build ./...` succeeds
+- `go test ./cmd/... ./pkg/dorks/... ./pkg/storage/...` passes
+- `./keyhunter dorks list --source=github --category=frontier` shows real dorks
+- `./keyhunter dorks run --source=shodan --id=shodan-ollama-default` emits ErrSourceNotImplemented message
+</verification>
+
+<success_criteria>
+- DORK-03 satisfied: list, run, add, export, info, delete all functional
+- DORK-04 satisfied: --source and --category filters applied in both list and run
+- dorks stub removed from cmd/stubs.go
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/08-dork-engine/08-06-SUMMARY.md`
+</output>