feat: adding dawgrun

go.mod

@@ -18,6 +18,19 @@ require (
 	github.com/stretchr/testify v1.11.1
 )
 
+// Dawgrun requirements
+require (
+	github.com/alecthomas/chroma/v2 v2.23.1
+	github.com/charmbracelet/lipgloss v1.1.0
+	github.com/davecgh/go-spew v1.1.1
+	github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510
+	github.com/jedib0t/go-pretty/v6 v6.7.8
+	github.com/kanmu/go-sqlfmt v0.0.2-0.20200215095417-d1e63e2ee5eb
+	github.com/mitchellh/go-wordwrap v1.0.1
+	github.com/specterops/go-repl v1.0.1
+	golang.org/x/term v0.39.0
+)
+
 require (
 	4d63.com/gocheckcompilerdirectives v1.3.0 // indirect
 	4d63.com/gochecknoglobals v0.2.2 // indirect
@@ -37,7 +50,6 @@ require (
 	github.com/Masterminds/semver/v3 v3.4.0 // indirect
 	github.com/MirrexOne/unqueryvet v1.5.4 // indirect
 	github.com/OpenPeeDeeP/depguard/v2 v2.2.1 // indirect
-	github.com/alecthomas/chroma/v2 v2.23.1 // indirect
 	github.com/alecthomas/go-check-sumtype v0.3.1 // indirect
 	github.com/alexkohler/nakedret/v2 v2.0.6 // indirect
 	github.com/alexkohler/prealloc v1.1.0 // indirect
@@ -72,7 +84,6 @@ require (
 	github.com/ccojocar/zxcvbn-go v1.0.4 // indirect
 	github.com/charithe/durationcheck v0.0.11 // indirect
 	github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc // indirect
-	github.com/charmbracelet/lipgloss v1.1.0 // indirect
 	github.com/charmbracelet/x/ansi v0.10.1 // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd // indirect
 	github.com/charmbracelet/x/term v0.2.1 // indirect
@@ -81,7 +92,6 @@ require (
 	github.com/curioswitch/go-reassign v0.3.0 // indirect
 	github.com/daixiang0/gci v0.13.7 // indirect
 	github.com/dave/dst v0.27.3 // indirect
-	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/denis-tingaikin/go-header v0.5.0 // indirect
 	github.com/dgryski/go-metro v0.0.0-20250106013310-edb8663e5e33 // indirect
 	github.com/dlclark/regexp2 v1.11.5 // indirect
@@ -175,6 +185,7 @@ require (
 	github.com/nunnatsa/ginkgolinter v0.23.0 // indirect
 	github.com/pelletier/go-toml v1.9.5 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/prometheus/client_golang v1.12.1 // indirect
 	github.com/prometheus/client_model v0.2.0 // indirect
@@ -247,4 +258,7 @@ require (
 	mvdan.cc/unparam v0.0.0-20251027182757-5beb8c8f8f15 // indirect
 )
 
-tool github.com/golangci/golangci-lint/v2/cmd/golangci-lint
+tool (
+	github.com/golangci/golangci-lint/v2/cmd/golangci-lint
+	github.com/specterops/dawgs/tools/dawgrun/cmd/dawgrun
+)

go.sum

@@ -363,6 +363,8 @@ github.com/google/pprof v0.0.0-20200708004538-1a94d8640e99/go.mod h1:ZgVRPoUq/hf
 github.com/google/pprof v0.0.0-20260115054156-294ebfa9ad83 h1:z2ogiKUYzX5Is6zr/vP9vJGqPwcdqsWjOt+V8J7+bTc=
 github.com/google/pprof v0.0.0-20260115054156-294ebfa9ad83/go.mod h1:MxpfABSjhmINe3F1It9d+8exIHFvUqtLIRCdOGNXqiI=
 github.com/google/renameio v0.1.0/go.mod h1:KWCgfxg9yswjAJkECMjeO8J8rahYeXnNhOm40UhjYkI=
+github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 h1:El6M4kTTCOh6aBiKaUGG7oYTSPP8MxqL4YI3kZKwcP4=
+github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510/go.mod h1:pupxD2MaaD3pAXIBCelhxNneeOaAeabZDe5s4K6zSpQ=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/googleapis/gax-go/v2 v2.0.4/go.mod h1:0Wqv26UfaUD9n4G6kQubkQ+KchISgw+vpHVxEJEs9eg=
@@ -454,6 +456,8 @@ github.com/jackc/puddle v1.1.3/go.mod h1:m4B5Dj62Y0fbyuIc15OsIqK0+JU8nkqQjsgx7dv
 github.com/jackc/puddle v1.3.0/go.mod h1:m4B5Dj62Y0fbyuIc15OsIqK0+JU8nkqQjsgx7dvjSWk=
 github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
 github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
+github.com/jedib0t/go-pretty/v6 v6.7.8 h1:BVYrDy5DPBA3Qn9ICT+PokP9cvCv1KaHv2i+Hc8sr5o=
+github.com/jedib0t/go-pretty/v6 v6.7.8/go.mod h1:YwC5CE4fJ1HFUDeivSV1r//AmANFHyqczZk+U6BDALU=
 github.com/jgautheron/goconst v1.8.2 h1:y0XF7X8CikZ93fSNT6WBTb/NElBu9IjaY7CCYQrCMX4=
 github.com/jgautheron/goconst v1.8.2/go.mod h1:A0oxgBCHy55NQn6sYpO7UdnA9p+h7cPtoOZUmvNIako=
 github.com/jingyugao/rowserrcheck v1.1.1 h1:zibz55j/MJtLsjP1OF4bSdgXxwL1b+Vn7Tjzq7gFzUs=
@@ -473,6 +477,8 @@ github.com/julz/importas v0.2.0 h1:y+MJN/UdL63QbFJHws9BVC5RpA2iq0kpjrFajTGivjQ=
 github.com/julz/importas v0.2.0/go.mod h1:pThlt589EnCYtMnmhmRYY/qn9lCf/frPOK+WMx3xiJY=
 github.com/kamstrup/intmap v0.5.2 h1:qnwBm1mh4XAnW9W9Ue9tZtTff8pS6+s6iKF6JRIV2Dk=
 github.com/kamstrup/intmap v0.5.2/go.mod h1:gWUVWHKzWj8xpJVFf5GC0O26bWmv3GqdnIX/LMT6Aq4=
+github.com/kanmu/go-sqlfmt v0.0.2-0.20200215095417-d1e63e2ee5eb h1:Ztn62UtaXoFlHJIrH0AuNQrMhE355paIqZn3ik6bHNk=
+github.com/kanmu/go-sqlfmt v0.0.2-0.20200215095417-d1e63e2ee5eb/go.mod h1:1+jKeqi65LLLs1GSNFRn4G/dkgg3TWeT6DTZLLQP2eM=
 github.com/karamaru-alpha/copyloopvar v1.2.2 h1:yfNQvP9YaGQR7VaWLYcfZUlRP2eo2vhExWKxD/fP6q0=
 github.com/karamaru-alpha/copyloopvar v1.2.2/go.mod h1:oY4rGZqZ879JkJMtX3RRkcXRkmUvH0x35ykgaKgsgJY=
 github.com/kisielk/errcheck v1.10.0 h1:Lvs/YAHP24YKg08LA8oDw2z9fJVme090RAXd90S+rrw=
@@ -601,6 +607,7 @@ github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0
 github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
 github.com/pkg/errors v0.8.0/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pkg/errors v0.8.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
@@ -683,6 +690,8 @@ github.com/sonatard/noctx v0.5.1 h1:wklWg9c9ZYugOAk7qG4yP4PBrlQsmSLPTvW1K4PRQMs=
 github.com/sonatard/noctx v0.5.1/go.mod h1:64XdbzFb18XL4LporKXp8poqZtPKbCrqQ402CV+kJas=
 github.com/sourcegraph/go-diff v0.7.0 h1:9uLlrd5T46OXs5qpp8L/MTltk0zikUGi0sNNyCpA8G0=
 github.com/sourcegraph/go-diff v0.7.0/go.mod h1:iBszgVvyxdc8SFZ7gm69go2KDdt3ag071iBaWPF6cjs=
+github.com/specterops/go-repl v1.0.1 h1:+rHsCkC8TplTr3qZCitA64xSpBXLF7hqqH5nTa8qnMQ=
+github.com/specterops/go-repl v1.0.1/go.mod h1:sv0wjdiFEM2QljRCyIRZN3rZ58fa2IzMwLFGTSu8lDY=
 github.com/spf13/afero v1.15.0 h1:b/YBCLWAJdFWJTN9cLhiXXcD7mzKn9Dm86dNnfyQw1I=
 github.com/spf13/afero v1.15.0/go.mod h1:NC2ByUVxtQs4b3sIUphxK0NioZnmxgyCrfzeuq8lxMg=
 github.com/spf13/cast v1.5.0 h1:rj3WzYc11XZaIZMPKmwP96zkFEnnAmV8s6XbB2aY32w=
@@ -992,6 +1001,8 @@ golang.org/x/term v0.8.0/go.mod h1:xPskH00ivmX89bAKVGSKKtLOWNx2+17Eiy94tnKShWo=
 golang.org/x/term v0.12.0/go.mod h1:owVbMEjm3cBLCHdkQu9b1opXd4ETQWc3BhuQGKgXgvU=
 golang.org/x/term v0.13.0/go.mod h1:LTmsnFJwVN6bCy1rVCoS+qHT1HhALEFxKncY3WNNh4U=
 golang.org/x/term v0.17.0/go.mod h1:lLRBjIVuehSbZlaOtGMbcMncT+aqLLLmKrsjNrUguwk=
+golang.org/x/term v0.39.0 h1:RclSuaJf32jOqZz74CkPA9qFuVTX7vhLlpfj/IGWlqY=
+golang.org/x/term v0.39.0/go.mod h1:yxzUCTP/U+FzoxfdKmLaA0RV1WgE0VY7hXBwKtY/4ww=
 golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.1-0.20180807135948-17ff2d5776d2/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=

tools/dawgrun/.gitignore

@@ -0,0 +1,2 @@
+.build.env
+dawgrun

tools/dawgrun/README.md

@@ -0,0 +1,193 @@
+```
+                            .--~~,__
+               :-....,-------`~~'._.'
+                `-,,,  ,_      ;'~U'
+                 _,-' ,'`-__; '--.
+                (_/'~~      ''''(;
+
+               ,---.            ,-.-.      _,---.
+  _,..---._  .--.'  \  ,-..-.-./  \==\ _.='.'-,  \
+/==/,   -  \ \==\-/\ \ |, \=/\=|- |==|/==.'-     /
+|==|   _   _\/==/-|_\ ||- |/ |/ , /==/==/ -   .-'
+|==|  .=.   |\==\,   - \\, ,     _|==|==|_   /_,-.
+|==|,|   | -|/==/ -   ,|| -  -  , |==|==|  , \_.' )
+|==|  '='   /==/-  /\ - \\  ,  - /==/\==\-  ,    (
+|==|-,   _`/\==\ _.\=\.-'|-  /\ /==/  /==/ _  ,  /
+`-.`.____.'  `--`        `--`  `--`   `--`------'
+                                 .-._
+         .-.,.---.  .--.-. .-.-./==/ \  .-._
+        /==/  `   \/==/ -|/=/  ||==|, \/ /, /
+       |==|-, .=., |==| ,||=| -||==|-  \|  |
+       |==|   '='  /==|- | =/  ||==| ,  | -|
+       |==|- ,   .'|==|,  \/ - ||==| -   _ |
+       |==|_  . ,'.|==|-   ,   /|==|  /\ , |
+       /==/  /\ ,  )==/ , _  .' /==/, | |- |
+       `--`-`--`--'`--`..---'   `--`./  `--`
+```
+
+`dawgrun` is a work-in-progress developer tool for interacting with
+`DAWGS` and the data structures it produces.
+
+It currently runs as a REPL for introspecting a `DAWGS`-compatible
+Postgres graph, parsing and translating Cypher queries, and executing
+queries against a live connection.
+
+## Building
+
+From a `DAWGS` checkout:
+
+    go tool dawgrun
+
+With a customized `DAWGS` clone, for testing features, version differences, etc:
+
+    cd tools/dawgrun
+    just build-with-dawgs path/to/DAWGS
+
+To switch the build back to mainline:
+
+    cd tools/dawgrun
+    just build-with-upstream
+
+## Running
+
+You are dropped into a prompt:
+
+    dawgrun >
+
+At any time, run `help` to list commands or `help <command>` for
+detailed usage, flag defaults, and description.
+
+## Commands
+
+The REPL supports command-name completion with `Tab`; ambiguous matches render a transient popover list near the prompt and can be dismissed with `Esc`.
+
+Available commands:
+
+```
+    exit                            Quit
+    explain-psql                    Explains a translated query over an active PG connection
+    help                            This help message, but also more detailed help for individual commands
+    load-db-kinds                   Loads/shows the kind mapping from the specified DB into the 'active set'
+    lookup-kind                     Looks up a kind from database based on kind name
+    lookup-kind-id                  Looks up a kind from database based on kind ID
+    open-pg-db                      Connects to a specified DAWGS-compatible Postgres DB to do graph introspection.
+    parse                           Parses and dumps a Cypher query to AST form.
+    query-cypher                    Executes a Cypher query and renders table or JSON output
+    quit                            Quit
+    runtime-trace                   Manage runtime tracing
+    translate-psql                  Parses a query and converts it to the underlying PostgreSQL query
+```
+
+### Connections and kind maps
+
+Most commands that touch a database take a connection _name_ as their
+first argument. Names are assigned when you open the connection and
+are reused for the remainder of the session. The bottom-right status
+widget shows the current number of open connections.
+
+A "kind map" is the mapping between a graph's kind names (e.g.
+`User`, `Group`) and the numeric IDs they are stored under in
+Postgres. Commands that need to translate between the two
+(`lookup-kind`, `lookup-kind-id`, and the `-conn` mode of
+`translate-psql`) will lazily fetch a kind map from the database the
+first time they need it; `load-db-kinds` forces an immediate refresh
+and dumps the result.
+
+## Examples
+
+### Open a Postgres connection
+
+    dawgrun > open-pg-db local "postgres://dawgs:dawgs@localhost:5432/dawgs?sslmode=disable"
+    Opened connection 'local': postgres://dawgs:dawgs@localhost:5432/dawgs?sslmode=disable
+
+The first argument (`local`) is the name other commands will refer
+to; the second is any DAWGS-compatible Postgres connection string.
+
+### Inspect kinds
+
+Load and dump the kind mapping from a connection:
+
+    dawgrun > load-db-kinds local
+
+Resolve a kind name to its numeric ID:
+
+    dawgrun > lookup-kind local User
+    Kind User => 3
+
+…or go the other direction:
+
+    dawgrun > lookup-kind-id local 3
+    Kind ID 3 => User
+
+### Parse a Cypher query to AST
+
+    dawgrun > parse "match (n:User) where n.name = 'alice' return n"
+
+The REPL highlights the dumped AST as Go source.
+
+> **Quoting note:** the REPL splits input with shell-style rules
+> (via `shlex`), so double quotes are consumed by the line parser
+> before the Cypher parser ever sees them. Cypher string literals
+> must use single quotes, and queries that contain them are easiest
+> to pass as a single double-quoted argument, e.g.
+> `"match (n) where n.name = 'alice' return n"`.
+
+### Translate Cypher to PostgreSQL
+
+Without a connection (kinds remain symbolic):
+
+    dawgrun > translate-psql match (n:User) return n limit 10
+
+With a connection, so that kind names are resolved to the IDs in the
+target database:
+
+    dawgrun > translate-psql -conn local match (n:User) return n limit 10
+
+To also see the translator's internal SQL AST alongside the formatted
+query:
+
+    dawgrun > translate-psql -conn local -dump-pg-ast match (n:User) return n limit 10
+
+### Ask Postgres to EXPLAIN a translated query
+
+Runs the translation, prepends `EXPLAIN`, and dispatches it over the
+named connection:
+
+    dawgrun > explain-psql local "match (n:User) where n.name = 'alice' return n"
+
+### Execute a Cypher query
+
+Default `table` output:
+
+    dawgrun > query-cypher local match (n:User) return n.name, n.objectid limit 5
+
+`json` output, useful for piping into other tooling:
+
+    dawgrun > query-cypher -format json local match (n:User) return n.name, n.objectid limit 5
+
+An empty result set renders as `(0 rows)` in table mode and `[]` in
+JSON mode.
+
+### Runtime tracing
+
+Capture a Go runtime trace for a subsequent command or block of work.
+The trace file defaults to `trace.out` in the current directory:
+
+    dawgrun > runtime-trace start
+    dawgrun > query-cypher local match (n) return count(n)
+    dawgrun > runtime-trace stop
+
+Open the resulting trace with `go tool trace trace.out`.
+
+## History
+
+The REPL persists command history to
+`$XDG_CONFIG_HOME/dawgrun/history.txt` (or the platform equivalent),
+capped at 1000 lines, so recent commands are available via the
+arrow keys across sessions.
+
+## Styling
+
+Syntax highlighting style defaults to `monokai`, but can be configured via
+the `DAWGRUN_STYLE` environment variable. 
+Any styles in [Chroma](https://github.com/alecthomas/chroma/tree/master/styles) are available for use as a syntax highlighting style. 

tools/dawgrun/cmd/dawgrun/art.txt

@@ -0,0 +1,5 @@
+                            .--~~,__
+               :-....,-------`~~'._.'
+                `-,,,  ,_      ;'~U'
+                 _,-' ,'`-__; '--.
+                (_/'~~      ''''(;

tools/dawgrun/cmd/dawgrun/banner.txt

@@ -0,0 +1,18 @@
+               ,---.            ,-.-.      _,---.  
+  _,..---._  .--.'  \  ,-..-.-./  \==\ _.='.'-,  \ 
+/==/,   -  \ \==\-/\ \ |, \=/\=|- |==|/==.'-     / 
+|==|   _   _\/==/-|_\ ||- |/ |/ , /==/==/ -   .-'  
+|==|  .=.   |\==\,   - \\, ,     _|==|==|_   /_,-. 
+|==|,|   | -|/==/ -   ,|| -  -  , |==|==|  , \_.' )
+|==|  '='   /==/-  /\ - \\  ,  - /==/\==\-  ,    ( 
+|==|-,   _`/\==\ _.\=\.-'|-  /\ /==/  /==/ _  ,  / 
+`-.`.____.'  `--`        `--`  `--`   `--`------'  
+                                 .-._              
+         .-.,.---.  .--.-. .-.-./==/ \  .-._       
+        /==/  `   \/==/ -|/=/  ||==|, \/ /, /      
+       |==|-, .=., |==| ,||=| -||==|-  \|  |       
+       |==|   '='  /==|- | =/  ||==| ,  | -|       
+       |==|- ,   .'|==|,  \/ - ||==| -   _ |       
+       |==|_  . ,'.|==|-   ,   /|==|  /\ , |       
+       /==/  /\ ,  )==/ , _  .' /==/, | |- |       
+       `--`-`--`--'`--`..---'   `--`./  `--`