Merge pull request #268 from jolt-lang/cli/nrepl-server-flag

cli: rename nrepl command to --nrepl-server flag

README.md

@@ -45,6 +45,32 @@ $ bin/joltc -e '(/ 1 2)'
 1/2
 ```
 
+## REPL and editor integration
+
+```bash
+bin/joltc repl                  # a line REPL with the project's deps loaded
+bin/joltc --nrepl-server [port] # an nREPL server (default 7888) for editors
+```
+
+Both resolve the `deps.edn` in the current directory first, so the project's
+source roots and native libraries are loaded — `(require '[my.ns])` works live.
+`--nrepl-server` writes a `.nrepl-port` file in the project dir, so CIDER / Calva / Cursive
+auto-detect the port; override it with the argument or `JOLT_NREPL_PORT`.
+
+The server runs in dev mode — calls deref their var, so redefining a function
+takes effect on the next call without restarting the process. The built-in
+handler speaks `clone`/`describe`/`eval`/`load-file`/`close`; heavier ops
+(sessions, interruptible eval, completion) are added as nREPL middleware listed
+in `deps.edn` under `:nrepl/middleware`.
+
+```clojure
+;; from your editor, against the running process:
+(require '[myapp.core :as app])
+(app/start!)                  ; bring the app up
+;; edit a handler, re-evaluate the defn — the running app sees it, no restart
+(app/stop!)
+```
+
 ## Compile a binary
 
 `bin/joltc build` ahead-of-time compiles a project into a single self-contained

docs/building-and-deps.md

@@ -57,14 +57,14 @@ dependencies, and prepends the resolved source directories to the source roots
 for the run. The CLI commands (`jolt.deps` + `jolt.main`):
 
 ```bash
-bin/joltc run -m NS [args]  # resolve deps.edn, load NS, call its -main
-bin/joltc run FILE          # resolve deps.edn, load a Clojure file
-bin/joltc -M:alias [args]   # run the alias's :main-opts
-bin/joltc -A:alias [args]   # add the alias's paths/deps, then run the rest
-bin/joltc repl              # start a line REPL (project deps + native libs loaded)
-bin/joltc nrepl [port]      # start an nREPL server (default 7888) for editors
-bin/joltc path              # print the resolved source roots (':'-joined)
-bin/joltc <task>            # run a deps.edn :tasks entry
+bin/joltc run -m NS [args]      # resolve deps.edn, load NS, call its -main
+bin/joltc run FILE              # resolve deps.edn, load a Clojure file
+bin/joltc -M:alias [args]       # run the alias's :main-opts
+bin/joltc -A:alias [args]       # add the alias's paths/deps, then run the rest
+bin/joltc repl                  # start a line REPL (project deps + native libs loaded)
+bin/joltc --nrepl-server [port] # start an nREPL server (default 7888) for editors
+bin/joltc path                  # print the resolved source roots (':'-joined)
+bin/joltc <task>                # run a deps.edn :tasks entry
 ```
 
 Example `deps.edn`:

host/chez/smoke.sh

@@ -46,6 +46,15 @@ check '(== 3 3.0)' 'true'
 check_loc '(throw (ex-info "boom" {}))' '  at 1:'
 check_loc '(do (+ 1 1) (/ 1 0))' '  at 1:'
 
+# --help prints usage, and lists the nREPL server under its real flag name.
+help_out="$(bin/joltc --help 2>/dev/null)"
+if printf '%s' "$help_out" | grep -q -- '--nrepl-server'; then
+  pass=$((pass + 1))
+else
+  echo "  FAIL: --help should list --nrepl-server"
+  fails=$((fails + 1))
+fi
+
 # clojure.test extension points (assert-expr / do-report / report) need separate
 # top-level forms — assert-expr must register before `is` expands — so this is a
 # multi-form `joltc run`, not an -e one-liner. The file self-checks its tallies.

jolt-core/jolt/main.clj

@@ -192,23 +192,26 @@
 
 (defn- usage []
   (println "usage: jolt <command> [args]")
-  (println "  run -m NS [args]   resolve deps.edn, load NS, call its -main")
-  (println "  run FILE           load a Clojure file")
+  (println "  run -m NS [args]       resolve deps.edn, load NS, call its -main")
+  (println "  run FILE               load a Clojure file")
   (println "  build -m NS [-o OUT] [--opt|--dev] [--direct-link] [--tree-shake]  compile a standalone binary")
-  (println "  -M:alias [args]    run the alias's :main-opts")
-  (println "  -A:alias [args]    add the alias's paths/deps")
-  (println "  repl               start a line REPL")
-  (println "  nrepl [port]       start an nREPL server (default 7888) for editors")
-  (println "  path               print the resolved source roots")
-  (println "  <task>             run a deps.edn :tasks entry"))
+  (println "  -M:alias [args]        run the alias's :main-opts")
+  (println "  -A:alias [args]        add the alias's paths/deps")
+  (println "  repl                   start a line REPL")
+  (println "  --nrepl-server [port]  start an nREPL server (default 7888) for editors")
+  (println "  path                   print the resolved source roots")
+  (println "  <task>                 run a deps.edn :tasks entry")
+  (println "  --help                 print this message"))
 
 (defn -main [& args]
   (let [[cmd & more] args]
     (cond
       (nil? cmd)                  (usage)
+      (= cmd "--help")            (usage)
+      (= cmd "-h")                (usage)
       (= cmd "run")               (cmd-run more)
       (= cmd "repl")              (repl)
-      (= cmd "nrepl")             (nrepl more)
+      (= cmd "--nrepl-server")    (nrepl more)
       (= cmd "path")              (cmd-path)
       (str/starts-with? cmd "-M") (cmd-M cmd more)
       (str/starts-with? cmd "-A") (cmd-A cmd more)