[Fix #2698] Infer available figwheel builds automatically

This commit also expands the documentation for working with figwheel.

Author: inwalkeddub

cider.el

@@ -762,13 +762,24 @@ Figwheel for details."
   :safe (lambda (s) (or (null s) (stringp s)))
   :package-version '(cider . "0.18.0"))
 
+(defun cider--figwheel-main-get-builds ()
+  "Extract build names from the <build-id>.cljs.edn config files in the project root."
+  (let ((builds (directory-files (clojure-project-dir) nil ".*\\.cljs\\.edn")))
+    (mapcar (lambda (f) (string-match "^\\(.*\\)\\.cljs\\.edn" f)
+              (match-string 1 f)) builds)))
+
 (defun cider-figwheel-main-init-form ()
   "Produce the figwheel-main ClojureScript init form."
   (let ((form "(do (require 'figwheel.main) (figwheel.main/start %s))")
-        (options (string-trim
-                  (or cider-figwheel-main-default-options
-                      (read-from-minibuffer "Select figwheel-main build (e.g. :dev): ")))))
-    (format form (cider-normalize-cljs-init-options options))))
+        (builds (cider--figwheel-main-get-builds)))
+    (cond
+     (cider-figwheel-main-default-options
+      (format form (cider-normalize-cljs-init-options (string-trim cider-figwheel-main-default-options))))
+
+     (builds
+      (format form (cider-normalize-cljs-init-options (completing-read "Select figwheel-main build: " builds))))
+
+     (t (user-error "No figwheel-main build files (<build-id>.cljs.edn) were found")))))
 
 (defcustom cider-custom-cljs-repl-init-form nil
   "The form used to start a custom ClojureScript REPL.

doc/modules/ROOT/pages/basics/clojurescript.adoc

@@ -30,7 +30,7 @@ to connect to an already running nREPL server using
 
 To setup piggieback, add the following dependencies to your project
 (`project.clj` in a Leiningen based project or `build.boot` in a Boot
-project):
+project or `deps.edn`):
 
 [source,clojure]
 ----
@@ -56,11 +56,21 @@ or in `build.boot`:
   repl {:middleware '[cider.piggieback/wrap-cljs-repl]})
 ----
 
+or in `deps.edn`:
+
+[source,clojure]
+----
+{:aliases { :cider-cljs { :main-opts
+  ["-m" "nrepl.cmdline" "--middleware"
+   "[cider.nrepl/cider-middleware,cider.piggieback/wrap-cljs-repl]"]}}}
+----
+
 == Starting a ClojureScript REPL
 
-Open a file in your project and type kbd:[M-x]
-`cider-jack-in-cljs` kbd:[RET]. This will start up the nREPL
-server and create a ClojureScript REPL buffer.
+Open a ClojureScript file in your project and type kbd:[M-x]
+`cider-jack-in-cljs` kbd:[RET]. With the correct configuration
+and after answering a few prompts this will start up the
+nREPL server and create a ClojureScript REPL buffer.
 
 NOTE: Prior to CIDER 0.18, `cider-jack-in-cljs` would create both a Clojure and
 a ClojureScript REPL. In CIDER 0.18+ if you want to create both REPLs
@@ -99,7 +109,7 @@ You can also modify the known ClojureScript REPLs on a per-project basis using
 
 [source,lisp]
 ----
-;; replace the list of REPLs types and set some default
+;; replace the list of REPL types and set some default
 ((nil
   (cider-default-cljs-repl . super-cljs)
   (cider-cljs-repl-types . ((super-cljs "(do (foo) (bar))")))))
@@ -130,7 +140,7 @@ ClojureScript REPL, you can invoke
 == Setting up a ClojureScript REPL
 
 The following sections describe the configurations for several common
-CloudScript REPL use cases.
+ClojureScript REPL use cases.
 
 === Browser-Connected ClojureScript REPL
 
@@ -233,6 +243,11 @@ them to your favourite build tool is up to you.
 
 You can also use https://github.com/bhauman/figwheel-main[Figwheel-main] with CIDER.
 
+==== Leiningen figwheel-main setup
+
+NOTE: This setup is only necessary if `cider-inject-dependencies-at-jack-in` has
+been changed from its default setting of `enabled`, as described more fully above.
+
 . Add this to your dev `:dependencies` (not needed for `cider-jack-in-cljs`):
 +
 [source,clojure]
@@ -248,9 +263,57 @@ You can also use https://github.com/bhauman/figwheel-main[Figwheel-main] with CI
 ----
 +
 . Start the REPL with `cider-jack-in-cljs` (kbd:[C-c C-x (C-)j (C-)s]). When CIDER prompts about the ClojureScript REPL type,
-type `figwheel-main`.
+select `figwheel-main`.
 . Select the Figwheel build to run when prompted for it. (e.g. `:dev`).
 
+==== Clojure CLI figwheel-main setup
+
+. Ensure your `deps.edn` contains these dependencies available from an
+alias such as `fig`. These should already be present if you used the
+https://github.com/bhauman/figwheel-main-template[figwheel-main-template]
+with https://github.com/seancorfield/clj-new[clj-new] to generate your
+deps.edn.
++
+[source,clojure]
+----
+{ :aliases {:fig {:extra-deps
+                 {com.bhauman/rebel-readline-cljs {:mvn/version "0.1.4"}
+                  com.bhauman/figwheel-main {:mvn/version "0.2.3"}}}}}
+----
++
+. Add this option to your project's `.dir-locals.el` before opening the
+ClojureScript file in a buffer from which you'll be starting the REPL.
+(If the file is already open you can either close and open it again or
+use `revert-buffer`.)
++
+[source,lisp]
+----
+((clojurescript-mode . ((cider-clojure-cli-global-options . "-A:fig"))))
+----
++
+. Start the REPL with `cider-jack-in-cljs` (kbd:[C-c C-x (C-)j (C-)s]).
+
+NOTE: If you didn't setup `.dir-locals.el` you can edit the command-line
+in the minibuffer and insert "-A:fig" at the beginning after the `clojure`
+executable. To do this prepend calling `cider-jack-in-cljs` with the
+universal argument (e.g. C-u).
+
+. When CIDER prompts for the ClojureScript REPL type, select `figwheel-main`.
+. When CIDER prompts for the build name, select one of the build name
+options which were generated by finding files named <build>.cljs.edn in
+the project root directory.
+
+WARNING: If instead of selecting one of the build name options provided,
+you enter either a non-existent build name (no matching .cljs.edn file)
+or an empty build name, CIDER will forward that on to figwheel-main which
+will report an error.
+
+NOTE: For more advanced usage, you can provide any options supported
+by `figwheel.main/start` at either the prompt for the build name or
+using the `cider-figwheel-main-default-options`.
+See https://github.com/bhauman/figwheel-main/blob/master/src/figwheel/main/api.clj[figwheel.main.api/start]
+for details.
+
 === Using shadow-cljs
 
 Provided you've configured your project correctly, you can simply use

doc/modules/ROOT/pages/basics/middleware_setup.adoc

@@ -12,12 +12,12 @@ automatically injects this middleware and other dependencies as required.
 NOTE: In the past, if you were setting up CIDER, you might have had to
 modify `profiles.clj` or `profile.boot`. CIDER now handles
 everything automatically and you don't need to add anything
-special to these files.
+special to these files. The same is true of your `deps.edn` file.
 
 If you prefer a standalone REPL, you will need to invoke
 `cider-connect` instead of `cider-jack-in` and manually add the
 dependencies to your Clojure project (explained in the following
-section).
+sections).
 
 == Setting Up a Standalone REPL
 
@@ -68,7 +68,22 @@ For more information visit https://github.com/boot-clj/boot/wiki/Cider-REPL[boot
 
 === Using tools.deps
 
-TODO
+You can add the following aliases to your deps.edn in order to launch
+a standalone Clojure(Script) nREPL server with CIDER middleware from
+the commandline with something like `clj -A:cider-clj`. Then from emacs
+run `cider-connect` or `cider-connect-cljs`.
+
+[source,clojure]
+----
+  :cider-clj {:extra-deps {cider/cider-nrepl {:mvn/version "0.22.3"}}
+              :main-opts ["-m" "nrepl.cmdline" "--middleware" "[cider.nrepl/cider-middleware]"]}
+
+  :cider-cljs {:extra-deps {org.clojure/clojurescript {:mvn/version "1.10.339"}
+                            cider/cider-nrepl {:mvn/version "0.22.3"}
+                            cider/piggieback {:mvn/version "0.4.1"}}
+               :main-opts ["-m" "nrepl.cmdline" "--middleware"
+                           "[cider.nrepl/cider-middleware,cider.piggieback/wrap-cljs-repl]"]}
+----
 
 === Using Gradle
 

test/cider-tests.el

@@ -55,16 +55,16 @@
       ;; not necessary as of this writing, but it can't hurt
       (setq-local cider-figwheel-main-default-options nil))
     (it "leaves keywords alone"
-      (spy-on 'read-from-minibuffer :and-return-value " :prod ")
+      (spy-on 'completing-read :and-return-value " :prod ")
       (expect (cider-figwheel-main-init-form) :to-equal "(do (require 'figwheel.main) (figwheel.main/start :prod))"))
     (it "leaves maps alone"
-      (spy-on 'read-from-minibuffer :and-return-value " {:c 3 :d 4}")
+      (spy-on 'completing-read :and-return-value " {:c 3 :d 4}")
       (expect (cider-figwheel-main-init-form) :to-equal "(do (require 'figwheel.main) (figwheel.main/start {:c 3 :d 4}))"))
     (it "leaves s-exprs alone"
-      (spy-on 'read-from-minibuffer :and-return-value "(keyword \"dev\") ")
+      (spy-on 'completing-read :and-return-value "(keyword \"dev\") ")
       (expect (cider-figwheel-main-init-form) :to-equal "(do (require 'figwheel.main) (figwheel.main/start (keyword \"dev\")))"))
     (it "prepends colon to plain names"
-      (spy-on 'read-from-minibuffer :and-return-value "prod ")
+      (spy-on 'completing-read :and-return-value "prod ")
       (expect (cider-figwheel-main-init-form) :to-equal "(do (require 'figwheel.main) (figwheel.main/start :prod))"))))
 
 (describe "cider-project-type"