switch Left to Right on help outputs; add draft transcripts (#1)

Maybe some duplication/conflicts here unintentionally.

The big transcript is just a WIP, we could make it prettier.

unison-cli/src/Unison/CommandLine/InputPatterns.hs

@@ -2312,12 +2312,12 @@ helpTopics =
     [("topic", Optional, topicNameArg)]
     ("`help-topics` lists all topics and `help-topics <topic>` shows an explanation of that topic.")
     ( \case
-        [] -> Left topics
+        [] -> Right $ Input.CreateMessage topics
         [topic] -> do
           topic <- unsupportedStructuredArgument "help-topics" "a help topic" topic
           case Map.lookup topic helpTopicsMap of
             Nothing -> Left . warn $ "I don't know of that topic. Try `help-topics`."
-            Just t -> Left t
+            Just t -> Right $ Input.CreateMessage t
         _ -> Left $ warn "Use `help-topics <topic>` or `help-topics`."
     )
   where
@@ -2497,21 +2497,21 @@ help =
     "`help` shows general help and `help <cmd>` shows help for one command."
     $ \case
       [] ->
-        Left $
+        Right . Input.CreateMessage $
           intercalateMap
             "\n\n"
             showPatternHelp
             visibleInputs
       [cmd] -> do
         cmd <- unsupportedStructuredArgument "help" "a command" cmd
         case (Map.lookup cmd commandsByName, isHelp cmd) of
-          (Nothing, Just msg) -> Left msg
+          (Nothing, Just msg) -> Right $ Input.CreateMessage msg
           (Nothing, Nothing) -> Left . warn $ "I don't know of that command. Try `help`."
-          (Just pat, Nothing) -> Left $ showPatternHelp pat
+          (Just pat, Nothing) -> Right . Input.CreateMessage $ showPatternHelp pat
           -- If we have a command and a help topic with the same name (like "projects"), then append a tip to the
           -- command's help that suggests running `help-topic command`
           (Just pat, Just _) ->
-            Left $
+            Right . Input.CreateMessage $
               showPatternHelp pat
                 <> P.newline
                 <> P.newline

unison-src/transcripts-manual/docs.to-html.output.md

@@ -6,7 +6,7 @@
   I'll now fetch the latest version of the base Unison
   library...
 
-  Downloaded 14053 entities.
+  Downloaded 12886 entities.
 
   🎨 Type `ui` to explore this project's code in your browser.
   🔭 Discover libraries at https://share.unison-lang.org

unison-src/transcripts/help.md

@@ -0,0 +1,14 @@
+# Shows `help` output
+
+```ucm:error
+scratch/main> help
+scratch/main> help-topics
+scratch/main> help-topic filestatus
+scratch/main> help-topic messages.disallowedAbsolute
+scratch/main> help-topic namespaces
+scratch/main> help-topic projects
+scratch/main> help-topic remotes
+scratch/main> help-topic testcache
+```
+
+We should add a command to show help for hidden commands also.

unison-src/transcripts/input-parse-errors.md

@@ -0,0 +1,173 @@
+# demonstrating our new input parsing errors
+
+```ucm:hide
+scratch/main> builtins.merge lib.builtin
+```
+
+```unison:hide
+x = 55
+```
+```ucm:hide
+scratch/main> add
+```
+
+`handleNameArg` parse error in `add`
+```ucm:error
+scratch/main> add .
+scratch/main> ls
+scratch/main> add 1
+scratch/main> ls
+scratch/main> add 2
+```
+
+todo:
+```haskell
+  SA.Name name -> pure name
+  SA.NameWithBranchPrefix (Left _) name -> pure name
+  SA.NameWithBranchPrefix (Right prefix) name -> pure $ Path.prefixNameIfRel (Path.AbsolutePath' prefix) name
+  SA.HashQualified hqname -> maybe (Left "can’t find a name from the numbered arg") pure $ HQ.toName hqname
+  SA.HashQualifiedWithBranchPrefix (Left _) hqname -> pure $ HQ'.toName hqname
+  SA.HashQualifiedWithBranchPrefix (Right prefix) hqname ->
+    pure . Path.prefixNameIfRel (Path.AbsolutePath' prefix) $ HQ'.toName hqname
+  SA.ShallowListEntry prefix entry ->
+    pure . HQ'.toName . fmap (Path.prefixNameIfRel prefix) $ shallowListEntryToHQ' entry
+  SA.SearchResult mpath result ->
+    maybe (Left "can’t find a name from the numbered arg") pure . HQ.toName $ searchResultToHQ mpath result
+  otherNumArg -> Left . I.Formatted $ wrongStructuredArgument "a name" otherNumArg
+```
+
+aliasMany: skipped -- similar to `add`
+
+```ucm:error
+scratch/main> update arg
+```
+
+aliasTerm
+```
+scratch/main> alias.term ##Nat.+ Nat.+
+```
+
+aliasTermForce,
+aliasType,
+
+
+todo:
+```
+
+aliasMany,
+api,
+authLogin,
+back,
+branchEmptyInputPattern,
+branchInputPattern,
+branchRenameInputPattern,
+branchesInputPattern,
+cd,
+clear,
+clone,
+compileScheme,
+createAuthor,
+debugClearWatchCache,
+debugDoctor,
+debugDumpNamespace,
+debugDumpNamespaceSimple,
+debugTerm,
+debugTermVerbose,
+debugType,
+debugLSPFoldRanges,
+debugFileHashes,
+debugNameDiff,
+debugNumberedArgs,
+debugTabCompletion,
+debugFuzzyOptions,
+debugFormat,
+delete,
+deleteBranch,
+deleteProject,
+deleteNamespace,
+deleteNamespaceForce,
+deleteTerm,
+deleteTermVerbose,
+deleteType,
+deleteTypeVerbose,
+deleteVerbose,
+dependencies,
+dependents,
+diffNamespace,
+display,
+displayTo,
+docToMarkdown,
+docs,
+docsToHtml,
+edit,
+editNamespace,
+execute,
+find,
+findIn,
+findAll,
+findInAll,
+findGlobal,
+findShallow,
+findVerbose,
+findVerboseAll,
+sfind,
+sfindReplace,
+forkLocal,
+help,
+helpTopics,
+history,
+ioTest,
+ioTestAll,
+libInstallInputPattern,
+load,
+makeStandalone,
+mergeBuiltins,
+mergeIOBuiltins,
+mergeOldInputPattern,
+mergeOldPreviewInputPattern,
+mergeOldSquashInputPattern,
+mergeInputPattern,
+mergeCommitInputPattern,
+names False, -- names
+names True, -- names.global
+namespaceDependencies,
+previewAdd,
+previewUpdate,
+printVersion,
+projectCreate,
+projectCreateEmptyInputPattern,
+projectRenameInputPattern,
+projectSwitch,
+projectsInputPattern,
+pull,
+pullWithoutHistory,
+push,
+pushCreate,
+pushExhaustive,
+pushForce,
+quit,
+releaseDraft,
+renameBranch,
+renameTerm,
+renameType,
+moveAll,
+reset,
+resetRoot,
+runScheme,
+saveExecuteResult,
+test,
+testAll,
+todo,
+ui,
+undo,
+up,
+update,
+updateBuiltins,
+updateOld,
+updateOldNoPatch,
+upgrade,
+upgradeCommitInputPattern,
+view,
+viewGlobal,
+viewReflog
+```