Calva like Jack-in options - improve UX especially for new users

[ieugen]

Hello,

I started with Clojure using VSCode and Calva and I was spoiled.
Now I am looking at emacs (mostly for org-mode), but tried it for clojure dev as well.

I opened an existing project and tried to jack-in a deps.edn project with some aliases.
And I noticed it's not that easy. Took me some looking around and I did not find a good solution.

How hard would it be to have a workflow similar to what Calva provides for VSCode?
The workflow is like this:

1. Run jack-in command
2. Chose project to jack-in from a list of project roots discovered by scanning current dir
   
3. Select project type - list built from scanning the project root for special files (deps.edn, shadow-cljs.edn, bb.edn, etc).
   
4. Based on project type load aliases - multi select
   

See clojurians slack discussion that sparked this discussion: https://clojurians.slack.com/archives/C01GE5PD249/p1733249488593309 .

I was surprised to find out that emacs does not have a minibuffer multi-select option OOTB so I asked on mastodon: https://mas.to/@ieugen/113590757327898330 .
I think multi-select in mini-buffer should be available in emacs OOTB and will probably raise an issue for this.

I got some code replies on how the feature would be implemented - not tested yet.
Thanks Teodor Heggelund for the code.

This almost works:

(defun eugen-slurp (filename)
  (with-temp-buffer
    (insert-file-contents filename)
    (buffer-string)))

(use-package parseedn)

(let* (;; first read the file
       (deps-edn-string (eugen-slurp "deps.edn"))
       ;; then parse the edn
       (deps-edn (parseedn-read-str deps-edn-string))
       ;; then get the list of aliases
       (aliases (hash-table-keys (gethash :aliases deps-edn)))
       ;; select the alias
       (selected-alias (completing-read "> which alias? " aliases))
       ;; finally, set the alias and jack in.
       cider-clojure-cli-aliases selected-alias)
  (cider-jack-in ()))

It appears to break between cider-clojure-cli-aliases and (cider-jack-in). I thought I could just bind the var in the let and have it passed in, but that didn't work as expected. When I inspected the resulting cider jack in command, no :dev was found. Perhaps somebody else can help with that final piece!
When that piece is in place, you can put all the code in an interactive function
(defun eugen-jack-in ()
(interactive)
;; ... all the code
)
and bind that to a key with doom's map! macro.

[ieugen]

it seems multi-select is possible with:

(completing-read-multiple "Select: " '("item1" "item2" "item3")) . 

Use Up/DOWN to navigate, TAB to select, and comma (,) to allow you to select new.

It's a bit more work than how this works in VSCode, but it's good it's there.

[ieugen]

I also got a reply on how to edit jack-in command from Burin:

I think you can still customise the command using the prefix command if you want to temporary edit custom jack-in command.
e.g. SPC u M-x cider-jack-in (plain emacs: C-u M-x cider-jack-in)

This works but the UX is terrible IMO, esp for beginners.
You get something long, hard to read, multi line, like this:

jack-in command: /usr/local/bin/clojure -Sdeps \{\:deps\ \{nrepl/nrepl\ \{\:mvn/version\ \"1.3.0\"\}\ cider/cider-nrepl\ \{\:mvn/version\ \"0.50.2\"\}\ refactor-nrepl/refactor-nrepl\ \{\:mvn/version\ \"3.10.0\"\}\}\ \:aliases\ \{\:cider/nrepl\ \{\:main-opts\ \[\"-m\"\ \"nrepl.cmdline\"\ \"--middleware\"\ \"\[refactor-nrepl.middleware/wrap-refactor\,cider.nrepl/cider-middleware\]\"\]\}\}\} -M:otp:cider/nrepl

[ieugen]

There seems to be a better UX for implementing this: emacs transient package.
https://github.com/magit/transient
Transient is bundled with emacs since 28.
Transient is used to implement the magit keyboard navigation (was developed for magit) .

See and run many examples using this repo https://github.com/positron-solutions/transient-showcase

Docs are here or inside emacs https://www.gnu.org/software/emacs/manual/html_mono/transient.html

[yuhan0]

I agree that a Transient-based UI for selecting the jack-in / connect options would be a nice enhancement – see eg. the Casual series of packages for inspiration: https://github.com/kickingvegas/casual

[alexander-yakushev]

There are a few issues with this proposal:

1. I personally would not want this feature enabled by default. This involves two prompts where there used to be none. I re-jack the REPLs quite often and I prefer not being bothered with additional questions.
2. The multi-select works well when there are few aliases. In some projects, it is not the case, for example: https://github.com/metabase/metabase/blob/master/deps.edn. In such projects, the selector might not even fit the entire screen and will be pretty useless.
3. Emacs UX is primarily about text manipulation, not clicking checkboxes. Users who prefer clicking usually pursue other editors 😄.

I think you can still customise the command using the prefix command if you want to temporary edit custom jack-in command.
e.g. SPC u M-x cider-jack-in (plain emacs: C-u M-x cider-jack-in)

This works but the UX is terrible IMO, esp for beginners.

I disagree. This is a very in-spirit-of-Emacs solution for multiple reasons:

• It lets you redefine not just the aliases but the whole command – you can also set custom env variables (e.g. override JAVA_HOME, I use that all the time), pass additional -J-Dproperties, etc.
• This is just text – you can copy-paste it from here to the terminal to try there and vice versa.
• It supports history, so you can cycle previous jack-in commands with M-p.
• The long line doesn't bother me much as it wraps, you still see all of it, navigate as regular text or move the cursor to where you need using mouse.

[ieugen]

Why so much resistance?
No one is forcing anyone to do anything. It's a discussion.

I personally would not want this feature enabled by default. This involves two prompts where there used to be none. I re-jack the REPLs quite often and I prefer not being bothered with additional questions.

This can be in addition, not in place of the regular cider jack-in flows IMO.

The multi-select works well when there are few aliases.

I'm sure there will be edge cases that won't fit, like with any tool.

Emacs UX is primarily about text manipulation, not clicking checkboxes.

Transient package is part of emacs and magit interface is soo good I use it in VSCode via edamagit package. Look maa', no mouse :) . I'm jesting a bit, hard to keep it in :) .

I disagree. This is a very in-spirit-of-Emacs solution for multiple reasons

Like I mentioned above, I never thought about dropping any existing feature.
Just add one that is menu / wizard driven so casual emacs users can discover options easier, without too much prior knowledge of in-spirit-of-Emacs solution .

[alexander-yakushev]

Why so much resistance?

We're having a discussion, just like you said. I don't know why you see it as resistance.

This can be in addition, not in place of the regular cider jack-in flows IMO.

Sure, it indeed can be an addition. But then a new user would have to know to use this jack-in over the "default" jack-in or whatever. Perhaps, this can be learned from the docs, but at that point the user can learn about the C-u M-x cider-jack-in too. So, if it's not on by default, then some discoverability value for a newcomer is lost.

I'm sure there will be edge cases that won't fit, like with any tool.

This indeed is not a big deal if the checkboxy jack-in is on a separate command/commands. But it's an extra point why enabling it by default may be inconvenient.

Transient package is part of emacs and magit interface is soo good I use it in VSCode via edamagit package.

I love Transient too in places where it is used. Your original suggestion was to use completing-read-multiple, so I'm replying to that. If you think Transient will be better, then it would be helpful to see an example/PoC of how it will look like for selecting aliases.

[alexander-yakushev]

Furthermore, customizing via cider-clojure-cli-aliases is actually very convenient. Most of the time, you don't really want to hand-pick the aliases, you just need a standard set of the "REPL" ones, and cider-clojure-cli-aliases solves that very well. Of course, this is very CIDER-specific, so it would be great to settle on some sort of a convention between CIDER/Calva/Cursive on how to define this default list of aliases cross-compatibly. For example, we could decide that the aliases that have e.g. :default true in their map would belong to such a default list, like this:

...
:aliases {:dev {:default true
                :extra-deps {...}

We can in fact start a discussion like that. What do you think, @bbatsov?

[ieugen]

so it would be great to settle on some sort of a convention between CIDER/Calva/Cursive on how to define this default list of aliases cross-compatibly

I agree, convention across tooling would be very nice. Learn once, apply many places.

[teodorlu]

I personally would not want this feature enabled by default. This involves two prompts where there used to be none. I re-jack the REPLs quite often and I prefer not being bothered with additional questions.

A different approach from asking the user on each jack-in could be to add UI to set aliases in .dir-locals.el based on a selection.

In that case, we wouldn't be changing jack-in's existing behavior, and users could opt to use the new UI if they want to.

[ieugen]

A different approach from asking the user on each jack-in could be to add UI to set aliases in .dir-locals.el based on a selection.

That might be an option as well. Not sure how much benefits it will bring.
For example, calva remembers the selected aliases and will pre-select them the next time you jack in.
This seems similar to what you are proposing and it might a place where a convention can be established to make Cider and Calva behave the same.

The issue with .dir-locals.el is that it is an elisp file which Calva does not know how to evaluate.
This is an instance where storing in json / edn or any other data file is preferable.
You don't need to evaluate those, you just need to parse them.