---
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>