Merge pull request #386 from rusq/v3-doc

Documentation and viewer fix on Windows

cmd/slackdump/internal/archive/assets/archive.md

@@ -1,33 +1,43 @@
-# Archive Command
+# Command: archive
 
-The archive command archives the Slack workspace into a directory of files.
-By default, it will perform the archiving of the full workspace that is accessible
-to your user.
+The `archive` command saves your Slack workspace as a directory of files. By
+default, it archives the entire workspace that your user can access. You can
+customize the archive to include specific channels, groups, or direct messages
+by providing their URLs or IDs.
 
-Optionally, one can select channels, groups and DMs to archive.  For this, one
-needs to specify the URLs or IDs of the channels.
+## Features
 
-The workspace is archived in the "Chunk" format, that can be viewed with the
-`view` command, or converted to other supported formats, such as native Slack
-Export format.
+### Default Behavior
+- Archives the full workspace accessible to your user.
 
-## What is contained in the archive?
+### Optional Customization
+- Specify channels, groups, or DMs to archive by providing their URLs or IDs.
 
-"Archive" behaves similarly to the Slackdump export feature, the output of a
-successful run contains the following:
-- channels.json.gz - list of channels in the workspace (full archives only);
-- users.json.gz - list of users in the workspace;
-- CXXXXXXX.json.gz - channel or group conversation messages, where XXXXXXX is
-  the channel ID;
-- DXXXXXXX.json.gz - direct messages, where XXXXXXX is the user ID;
+### Output Format
+- The archive uses the **"Chunk" format**, which can be:
+  - Viewed using the `view` command.
+  - Converted to other formats, including the native Slack Export format.
 
-Output format:
+## Archive Contents
 
-- Each file is a JSONL file compressed with GZIP.
+The archive behaves like the Slackdump export feature. A successful run
+output includes:
 
-Please note that "archive" can not create ZIP files, but you can zip the output
-directory manually.
+- **`channels.json.gz`**: A list of channels in the workspace (only for full
+  archives).
+- **`users.json.gz`**: A list of users in the workspace.
+- **`CXXXXXXX.json.gz`**: Messages from a channel or group, where `XXXXXXX` is
+  the channel ID.
+- **`DXXXXXXX.json.gz`**: Direct messages, where `XXXXXXX` is the user ID.
 
-## What is chunk file format?
+### File Format
+- Files are saved as **JSONL** (newline-delimited JSON) and compressed with
+  **GZIP**.
+- Note: The `archive` command does not create ZIP files, but you can manually
+  compress the output directory into a ZIP file if needed.
+
+## What is the Chunk Format?
+
+The Chunk format is a specific structure used for archiving data. For details
+on this format, run:  `slackdump help chunk`
 
-Run `slackdump help chunk` for the format specification.

cmd/slackdump/internal/archive/assets/search.md

@@ -0,0 +1,56 @@
+# Command: search
+
+The `search` command allows you to search and export messages or files from a
+Slack workspace based on specified query terms. This command supports searching
+for messages, files, or both, and outputs the results in a directory.
+
+### Subcommands
+- **`slackdump search messages`**: Searches and records messages matching the
+  given query.
+- **`slackdump search files`**: Searches and records files matching the given
+  query.
+- **`slackdump search all`**: Searches and records both messages and files
+  matching the query.
+
+### Flags
+- **`--no-channel-users`**: Skips retrieving user data for channels, making the
+  process approximately 2.5x faster.
+
+### Requirements
+- Authentication is required for all search operations.
+- An output directory must be specified (see configuration details).
+
+## Usage Examples
+
+### Search Messages
+
+```bash
+slackdump search messages "meeting notes"
+```
+
+### Search Files
+
+```bash
+slackdump search files "report"
+```
+
+### Search Messages and Files
+
+```bash
+slackdump search all "project updates"
+```
+
+### Faster Searches
+To speed up searches, add the `--no-channel-users` flag:
+
+```bash
+slackdump search messages -no-channel-users "status update"
+```
+
+
+## Output Directory
+The search command outputs results to the specified directory. The directory
+contains:
+
+- **`search.jsonl.gz`**: A list of messages matching the query.
+- directory with saved files (if files are included in the search).

cmd/slackdump/internal/archive/search.go

@@ -2,6 +2,7 @@ package archive
 
 import (
 	"context"
+	_ "embed"
 	"errors"
 	"log/slog"
 	"strings"
@@ -22,7 +23,7 @@ import (
 var CmdSearch = &base.Command{
 	UsageLine:   "slackdump search",
 	Short:       "dump search results",
-	Long:        `Searches for messages matching criteria.`,
+	Long:        searchMD,
 	Wizard:      wizSearch,
 	RequireAuth: true,
 	Commands: []*base.Command{
@@ -32,6 +33,9 @@ var CmdSearch = &base.Command{
 	},
 }
 
+//go:embed assets/search.md
+var searchMD string
+
 const flagMask = cfg.OmitUserCacheFlag | cfg.OmitCacheDir | cfg.OmitTimeframeFlag | cfg.OmitMemberOnlyFlag
 
 var cmdSearchMessages = &base.Command{

cmd/slackdump/internal/diag/edge.go

@@ -22,6 +22,8 @@ var cmdEdge = &base.Command{
 # Slack Edge API test tool
 
 Edge test attempts to call the Edge API with the provided credentials.
+
+Not particularly useful for end users, but can be used to test the Edge API.
 `,
 }
 
@@ -62,7 +64,7 @@ func runEdge(ctx context.Context, cmd *base.Command, args []string) error {
 	lg.Info("*** AdminEmojiList test ***")
 	var allEmoji edge.EmojiResult
 
-	var iter = 0
+	iter := 0
 	for res, err := range cl.AdminEmojiList(ctx) {
 		if err != nil {
 			return err

cmd/slackdump/internal/diag/uninstall.go

@@ -157,8 +157,8 @@ func uninstallPlaywright(ctx context.Context, si info.PwInfo, dry bool) error {
 	if err := removeFn(si.Path); err != nil {
 		return fmt.Errorf("failed to remove the playwright library: %w", err)
 	}
-	lg.InfoContext(ctx, "Deleting browsers", "browsers_path", si.BrowsersPath)
 
+	lg.InfoContext(ctx, "Deleting browsers", "browsers_path", si.BrowsersPath)
 	if err := removeFn(si.BrowsersPath); err != nil {
 		return fmt.Errorf("failed to remove the playwright browsers: %w", err)
 	}
@@ -218,13 +218,24 @@ func (p *uninstOptions) configuration() cfgui.Configuration {
 					Description: "Environment to uninstall (if unselected, uninstalls Rod)",
 					Updater:     updaters.NewBool(&p.playwright),
 				},
+				{
+					Name:        "Rod Browser",
+					Value:       cfgui.Checkbox(p.rod),
+					Description: "Browser to uninstall (if unselected, uninstalls Playwright)",
+					Updater:     updaters.NewBool(&p.rod),
+				},
+				{
+					Name:        "User cache",
+					Value:       cfgui.Checkbox(p.cache),
+					Description: "Remove all saved workspaces and user/channel cache",
+					Updater:     updaters.NewBool(&p.cache),
+				},
 				{
 					Name:        "Dry run",
 					Value:       cfgui.Checkbox(p.dry),
 					Description: "Do not perform the uninstallation, just show what would be done",
 					Updater:     updaters.NewBool(&p.dry),
 				},
-				// TODO: add an option to delete slackdump from user cache options.
 			},
 		},
 	}

cmd/slackdump/internal/diag/wizdebug.go

@@ -5,6 +5,7 @@ import (
 
 	tea "github.com/charmbracelet/bubbletea"
 	"github.com/charmbracelet/huh"
+
 	"github.com/rusq/slackdump/v3/cmd/slackdump/internal/golang/base"
 	"github.com/rusq/slackdump/v3/cmd/slackdump/internal/ui/bubbles/menu"
 	"github.com/rusq/slackdump/v3/cmd/slackdump/internal/ui/cfgui"
@@ -15,6 +16,7 @@ var cmdWizDebug = &base.Command{
 	Short:      "run the wizard debug command",
 	Run:        runWizDebug,
 	PrintFlags: true,
+	HideWizard: true,
 }
 
 type wdWhat int

cmd/slackdump/internal/emoji/assets/emoji.md

@@ -1,13 +1,13 @@
-# Emoji Command
-This command allows you to download all the custom emojis from the Slack
-workspace.
+# Command: emoji ฅ(^•ﻌ•^ฅ)
+This command allows you to download all emoticons from the Slack Workspace.
 
 There are two modes of operation:
-- **Standard**: download only the names and URLs of the custom emojis;
-- **Full**: Download all the custom emojis from the workspace.
+- **Standard**: download only the names and URLs of the workspace emojis;
+- **Full**: downloads all the information about the custom emojis from the
+  workspace.
 
-Full mode is approx. 2.3 times slower than the standard mode, but it provides
-more information about the custom emojis.
+Full mode is approximately 2.3 times slower than the standard mode, but it
+provides more information about the custom emojis.
 
 In both modes:
 - aliases are skipped, as they just point to the main emoji;

cmd/slackdump/internal/emoji/emoji.go

@@ -27,8 +27,8 @@ var emojiMD string
 var CmdEmoji = &base.Command{
 	Run:         run,
 	UsageLine:   "slackdump emoji [flags]",
-	Short:       "download custom workspace emojis",
-	Long:        emojiMD, // TODO: add long description
+	Short:       "download workspace emoticons ಠ_ಠ",
+	Long:        emojiMD,
 	FlagMask:    cfg.OmitDownloadFlag | cfg.OmitConfigFlag | cfg.OmitChunkCacheFlag | cfg.OmitUserCacheFlag,
 	RequireAuth: true,
 	PrintFlags:  true,
@@ -94,7 +94,6 @@ func statusReporter() (emojidl.StatusFunc, io.Closer) {
 		})
 		pb.Add(1)
 	}, pb
-
 }
 
 func runLegacy(ctx context.Context, fsa fsadapter.FS, cb emojidl.StatusFunc) error {

cmd/slackdump/internal/export/assets/export.md

@@ -0,0 +1,61 @@
+# Command: export
+
+The `export` command saves your Slack workspace as a directory of files.
+By default, it exports the entire workspace that your user can access.
+You can customize the archive to include specific channels, groups, or
+direct messages by providing their URLs or IDs.
+
+The ZIP file it generates is compatible with the Slack Export format with
+Slackdump specific extensions.
+
+The export file is understood by Slack Import feature with the following
+caveat:
+- files will not be imported, unless the `export` token is specified.
+  Github user @codeallthethingz has created a script that allows you to
+  import attachments from the export file.  You can find it
+  [here](https://github.com/rusq/slackdump/issues/371)
+
+
+## Export file structure
+
+```plaintext
+/
+├── __uploads              : all uploaded files are placed in this dir.
+│   └── F02PM6A1AUA        : slack file ID is used as a directory name
+│       └── Chevy.jpg      : file attachment
+├── everyone               : channel "#everyone"
+│   ├── 2022-01-01.json    :   all messages for the 1 Jan 2022.
+│   └── 2022-01-04.json    :    "     "      "   "  4 Jan 2022.
+├── DM12345678             : Your DMs with Scumbag Steve^
+│   └── 2022-01-04.json    :   (you did not have much to discuss —
+│                          :    Steve turned out to be a scumbag)
+├── channels.json          : all workspace channels information
+├── dms.json               : direct message information
+└── users.json             : all workspace users information
+```
+
+### Channels
+The channels are be saved in directories, named after the channel title,
+i.e. `#random` would be saved to "random" directory. The directory will
+contain a set of JSON files, one per each day.  If there were no
+conversations on some particular day, there will be no JSON file for that
+day.
+
+### Users
+User directories will have a "D" prefix, to find out the user name, check
+`users.json` file.
+
+### Group Messages
+Group messages will have all involved user handles in their name.
+
+## Inclusive and Exclusive Modes
+
+It is possible to **include** or **exclude** channels in/from the Export.
+
+For more details, run `slackdump help syntax`.
+
+## Viewing the Export
+
+To view the export, run `slackdump view <export_file>`.
+
+

cmd/slackdump/internal/export/export.go

@@ -2,6 +2,7 @@ package export
 
 import (
 	"context"
+	_ "embed"
 	"errors"
 	"fmt"
 	"strings"
@@ -23,23 +24,23 @@ var CmdExport = &base.Command{
 	UsageLine:   "slackdump export",
 	Short:       "exports the Slack Workspace or individual conversations",
 	FlagMask:    cfg.OmitUserCacheFlag,
-	Long:        ``, // TODO: add long description
+	Long:        mdExport, // TODO: add long description
 	CustomFlags: false,
 	PrintFlags:  true,
 	RequireAuth: true,
 }
 
+//go:embed assets/export.md
+var mdExport string
+
 type exportFlags struct {
 	ExportStorageType fileproc.StorageType
 	ExportToken       string
 }
 
-var (
-	compat  bool
-	options = exportFlags{
-		ExportStorageType: fileproc.STmattermost,
-	}
-)
+var options = exportFlags{
+	ExportStorageType: fileproc.STmattermost,
+}
 
 func init() {
 	CmdExport.Flag.Var(&options.ExportStorageType, "type", "export file storage type")