Add list-racket-packages and describe-racket-package

Issue greghendershott#710 planted the idea.

Largely follow the UX used by Emacs for its list-packages (a tabulated
list view) and describe-package (a help buffer with details).

In latter, "link all the things": can visit paths, URLs, and details
of dependency packages.

Append some general package system configuration. On the one hand this
is weird, because the information is not details about a specific
package. On the other hand, we distinguish it in the UX, and it seems
easier (for users) to see it there than needing to discover and issue
some additional command.

Support package names as a distinct 'racket-package completion
category, both to avoid things like marginalia mistakenly classifying
and annotating our choices, as well as to allow users to customize
completion styles.

Do package operations in each back end, to support a mix of Racket
version installations, both remote and local.

doc/generate.el

@@ -20,6 +20,7 @@
 (require 'racket-smart-open)
 (require 'racket-repl-buffer-name)
 (require 'racket-hash-lang)
+(require 'racket-package)
 (require 'seq)
 
 (defun racket-generate-reference.org ()
@@ -106,6 +107,10 @@
     racket-expand-region
     racket-expand-definition
     racket-expand-last-sexp
+    "Packages"
+    list-racket-packages
+    racket-package-mode
+    describe-racket-package
     "Other"
     racket-debug-toggle-breakpoint
     racket-mode-start-faster

doc/racket-mode.texi

@@ -90,6 +90,7 @@ Commands
 * Eval::
 * Collections::
 * Macro expand::
+* Packages::
 * Other::
 
 Edit
@@ -180,6 +181,12 @@ Macro expand
 * racket-expand-definition::
 * racket-expand-last-sexp::
 
+Packages
+
+* list-racket-packages::
+* racket-package-mode::
+* describe-racket-package::
+
 Other
 
 * racket-debug-toggle-breakpoint::
@@ -920,6 +927,7 @@ You can also view these by using the normal Emacs help mechanism:
 * Eval::
 * Collections::
 * Macro expand::
+* Packages::
 * Other::
 @end menu
 
@@ -2862,6 +2870,87 @@ Uses the @code{macro-debugger} package to do the expansion.
 With @kbd{C-u}  behaves as if @ref{racket-expand-hiding}
 were 'disabled.
 
+@node Packages
+@section Packages
+
+@menu
+* list-racket-packages::
+* racket-package-mode::
+* describe-racket-package::
+@end menu
+
+@node list-racket-packages
+@subsection list-racket-packages
+
+@kbd{M-x}  @code{list-racket-packages}
+
+Open a @ref{racket-package-mode} buffer for the active back end.
+
+@node racket-package-mode
+@subsection racket-package-mode
+
+@kbd{M-x}  @code{racket-package-mode}
+
+Major mode for Racket package management.
+
+The list of packages is equivalent to ``raco pkg show -all'' on
+the active back end.
+
+On each row you can press RET to @code{describe-racket-package}, which
+opens a buffer where you can view details, and use buttons to
+install/update/remove the package.
+
+@multitable {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaa}
+@item Key
+@tab Binding
+@item @kbd{RET} 
+@tab @code{racket-package-describe}
+@end multitable
+
+
+
+
+In addition to any hooks its parent mode @code{tabulated-list-mode} might
+have run, this mode runs the hook @code{racket-package-mode-hook}, as the
+final or penultimate step during initialization.
+
+@node describe-racket-package
+@subsection describe-racket-package
+
+@kbd{M-x}  @code{describe-racket-package}
+
+Describe details of a Racket package.
+
+Depending on the package status, buttons let you install, update,
+and/or remove the package and its dependencies. These convenience
+buttons are equivalent to using the command line on the active
+back end to do ``raco pkg @{install update remove@} --auto''. For
+other operations, you still need to use ``raco pkg'' yourself;
+see @uref{https://docs.racket-lang.org/pkg/cmdline.html}.
+
+Detail values are links when possible:
+
+@itemize
+@item
+The @emph{Catalog} (when ``@uref{https://pkgs.racket-lang.org}'') links to
+the package's web page, which may have additional details not
+available locally.
+
+@item
+The @emph{Source} links to the repo's web page or local filesystem.
+
+@item
+The @emph{Directory} for an installed package opens a dired buffer.
+
+@item
+Each @emph{Dependencies} name links to details about that package.
+
+@item
+For installed packages, each @emph{Modules} item links to the local
+file. There is also a button to each module's locally installed
+documentation, if any.
+@end itemize
+
 @node Other
 @section Other
 

racket-cmd.el

@@ -30,6 +30,9 @@
 (declare-function  racket--repl-on-output "racket-repl" (session-id kind value))
 (autoload         'racket--repl-on-output "racket-repl")
 
+(declare-function  racket--package-on-notify "racket-package" (v))
+(autoload         'racket--package-on-notify "racket-package")
+
 ;;;###autoload
 (defvar racket-start-back-end-hook nil
   "Hook run after `racket-start-back-end' finishes successfully.")
@@ -219,6 +222,8 @@ notifications."
      (run-at-time 0.001 nil #'racket--hash-lang-on-notify id vs))
     (`(repl-output ,session-id ,kind ,v)
      (run-at-time 0.001 nil #'racket--repl-on-output session-id kind v))
+    (`(pkg-op-notify . ,v)
+     (run-at-time 0.001 nil #'racket--package-on-notify v))
     (`(,nonce . ,response)
      (when-let (callback (gethash nonce racket--cmd-nonce->callback))
        (remhash nonce racket--cmd-nonce->callback)

racket-complete.el

@@ -56,22 +56,21 @@
 (add-to-list 'completion-category-defaults
              `(,racket--identifier-category (styles basic)))
 
-(defun racket--completion-table (completions &optional category)
-  "Like `completion-table-dynamic' but we supply category metadata.
+(defun racket--completion-table (completions &optional metadata)
+  "Like `completion-table-dynamic' but also metadata.
 
-CATEGORY defaults to `racket--identifier-category'.
+METADATA defaults to `((category . ,`racket--identifier-category')).
 
 Category metadata needs to be returned by the completion table
 function itself, unlike metadata supplied as properties in the
 `completion-at-point-functions' list.
 
 Supplying category metadata allows the user to configure a
 completion matching style for that category."
-  (let ((category (or category racket--identifier-category)))
-    (lambda (prefix predicate action)
-      (if (eq action 'metadata)
-          `(metadata (category . ,category))
-        (complete-with-action action completions prefix predicate)))))
+  (lambda (prefix predicate action)
+    (if (eq action 'metadata)
+        (cons 'metadata (or metadata `((category . ,racket--identifier-category))))
+      (complete-with-action action completions prefix predicate))))
 
 (provide 'racket-complete)
 

racket-hash-lang.el

@@ -88,6 +88,8 @@
     "---"
     ["Next Error or Link" next-error]
     ["Previous Error" previous-error]
+    "---"
+    ["List Racket Packages" list-racket-packages]
     ["Customize..." customize-mode]))
 
 (defvar-local racket--hash-lang-submit-predicate-p nil)

racket-mode.el

@@ -29,6 +29,7 @@
 (require 'racket-custom)
 (require 'racket-smart-open)
 (require 'racket-imenu)
+(require 'racket-package)
 (require 'racket-profile)
 (require 'racket-logger)
 (require 'racket-shell)
@@ -121,6 +122,7 @@
     ["Trim Requires" racket-trim-requires]
     ["Use #lang racket/base" racket-base-requires]
     "---"
+    ["List Racket Packages" list-racket-packages]
     ["Start Faster" racket-mode-start-faster]
     ["Customize..." customize-mode]))