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