@jals1212/pi-spaces-cli 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -6,6 +6,32 @@ commands and options and a patch version fixes.
 
 ## Unreleased
 
+## 0.6.1
+
+### Added
+
+- `pi-space <command> --help` (also `-h`, and `pi-space --help <command>`)
+  prints the help of one command: what it does, its arguments and options, the
+  call options that apply to it, and examples. `--help` anywhere after the
+  command word counts, so `pi-space remove work --help` prints the help and
+  removes nothing. After a space name it still belongs to Pi:
+  `pi-space work --help` starts Pi with `--help`. An unknown command exits with
+  status 2. It reads no config file and starts nothing.
+
+### Changed
+
+- Completion groups its candidates (commands, spaces, profiles, options) and
+  describes them: each command shows a one-line summary, `base` and the spaces
+  are told apart, a profile shows its command, and `remove` offers `--yes` and
+  `--no-backup`. `--help` is offered, as the options are, once the word starts
+  with `-`. The hidden `__complete` prints `<group>\t<value>\t<description>`
+  lines instead of bare words.
+- `pi-space -<TAB>` offers the call options not typed yet (`--profile`,
+  `--dir`, `--config`, `--command`, `--setup`), and `--help` and `--version`
+  when nothing comes before.
+- Completion no longer offers `completion` among the commands; it still works
+  typed in full, and `pi-space completion <TAB>` still offers `zsh`.
+
 ## 0.6.0
 
 ### Added

package/README.md

@@ -28,9 +28,12 @@ The command words are reserved: a space can never be named `list`, `new`, `remov
 | `pi-space install <name\|--every> <source> [pi install options...]` | Runs Pi's `install` in a space. The source is required. |
 | `pi-space uninstall <name\|--every> <source> [pi options...]` | Runs Pi's `uninstall` (its alias of `remove`) in a space. The source is required. |
 | `pi-space completion zsh` | Prints the zsh completion script (see [Shell completion](#shell-completion)). Any other shell, or none, exits with status 2. |
+| `pi-space <command> --help` | Shows the help of one command: what it does, its arguments and options, the call options that apply, and examples (`pi-space --help <command>` and `-h` work too). |
 | `pi-space --help` | Shows the usage. |
 | `pi-space --version` | Prints the version. |
 
+`--help` (or `-h`) anywhere after a command word shows that command's help and does nothing else: `pi-space remove work --help` removes nothing, and it reads no config file. After a space name every argument belongs to Pi, so `pi-space work --help` starts Pi with `--help`. An unknown command (`pi-space --help ghost`) exits with status 2 and lists the commands.
+
 `--new` and `--remove`, the options of 0.3, were replaced by `new` and `remove`; they exit with status 2 and name the command to use.
 
 ### Packages in a space, or in every space
@@ -160,7 +163,7 @@ alias my-space='pi-space --profile my'     # any POSIX shell
 
 ## Shell completion
 
-`pi-space` completes its commands, the profile names after `--profile`, files after `--config` and `--dir`, and the spaces. For zsh, add to `~/.zshrc` (after `compinit`):
+`pi-space` completes its commands (each with a one-line summary), the profile names after `--profile`, files after `--config` and `--dir`, and the spaces. For zsh, add to `~/.zshrc` (after `compinit`):
 
 ```sh
 source <(pi-space completion zsh)
@@ -170,14 +173,18 @@ It asks the command itself for the candidates each time, through the hidden `pi-
 
 | After | Candidates |
 | --- | --- |
-| `pi-space` (and the call options) | the commands, `base` and the spaces |
-| `--profile` | the profile names, `pi` included |
+| `pi-space` (and the call options) | the commands, then `base` and the spaces (`completion` is not offered, but works typed in full) |
+| `--profile` | the profile names, `pi` included, each with its command |
 | `--config`, `--dir` | files (the shell's own completion) |
 | `remove`, `rename` | the spaces |
 | `setup` | the spaces and `--every` |
 | `list`, `update`, `install`, `uninstall` | `base`, the spaces and `--every` |
 | `completion` | `zsh` |
 
+In first place the call options not typed yet come too, and `--help` and `--version` when nothing comes before. After a command word the options come too: `--help` for every command, and `--yes` and `--no-backup` after `remove`. zsh shows them once the word starts with `-`, so `pi-space new <TAB>` never fills in a lone `--help`.
+
+The candidates come in groups, each with a description, and zsh lists each group apart: commands, spaces (`base` is "the home Pi starts with"), profiles, shells and options. The hidden `pi-space __complete` prints one `<group>\t<value>\t<description>` line per candidate (or the single line `__files__` when the shell should complete a file), so a script for another shell can use it.
+
 Completion also works through an abbreviation or alias like the one above: they expand first, so `my-space <TAB>` completes what `pi-space --profile my <TAB>` would. A config file that is wrong, or a profile that does not exist, just gives no candidates; completion never prints an error.
 
 ## Preparing a new space

package/dist/cli.js

@@ -51,6 +51,7 @@ export const USAGE = `Usage: pi-space [--command <cmd>] [--dir <path>] [--setup
   pi-space install <name|--every> <source>    install a package in a space (more words go to Pi)
   pi-space uninstall <name|--every> <source>  remove a package from a space (more words go to Pi)
   pi-space completion zsh                     print the zsh completion script (source <(pi-space completion zsh))
+  pi-space <command> --help                   the help of one command
   pi-space --help                             print this help
   pi-space --version                          print the version
   --every takes the place of the name: base first (not for setup), then every space in turn; a failure does not stop the rest, and the exit status is 1 if any failed.
@@ -90,6 +91,7 @@ const REPLACED = {
 
                           
 	                  
+	                                           
 	                     
 	                                            
 	                                                       
@@ -109,6 +111,154 @@ const REPLACED = {
 
 const CALL_OPTIONS = { "--command": "command", "--dir": "dir", "--setup": "setup", "--profile": "profile", "--config": "config" }         ;
 
+function isHelpFlag(word        )          {
+	return word === "--help" || word === "-h";
+}
+
+/** What each call option is, for the help of the commands it applies to. */
+const CALL_HELP                                                           = {
+	command: ["--command <cmd>", 'the program to run instead of $PI_SPACES_COMMAND (default: pi), e.g. "my-launcher --"'],
+	dir: ["--dir <path>", "the spaces folder instead of $PI_SPACES_DIR; the Pi it starts gets it too"],
+	setup: ["--setup <cmd>", "the setup command instead of $PI_SPACES_SETUP; {home} and {name} become the space's folder and name"],
+	profile: ["--profile <name>", 'the profile of the config file instead of its "default"'],
+	config: ["--config <path>", "the config file instead of $PI_SPACES_CONFIG (default: ~/.pi-spaces/config.json)"],
+};
+
+/** The help of one command; the summary is the one line completion shows next to it. */
+                       
+	                
+	                                                  
+	              
+	                                                  
+	                
+	                                      
+	                                                         
+	                                                          
+	                                         
+	                             
+	                   
+ 
+
+const PI_ARGS                   = ["[pi args...]", "more words go to Pi, e.g. --extensions, --all or a source"];
+const NAME_OR_EVERY                     = [
+	["<name>", "base or a space"],
+	["--every", "base first, then every space in turn; a failure does not stop the rest, and the exit status is 1 if any failed"],
+];
+
+/** The commands, in the order completion lists them. They are reserved words: the core never lets a space be named one. */
+const COMMANDS                              = {
+	list: {
+		summary: "list the spaces, or the packages of one",
+		usage: "list [<name|--every>]",
+		about: ["With a name it runs Pi's list in that space; with --every, in base and then every space."],
+		args: NAME_OR_EVERY,
+		options: [],
+		calls: ["command", "dir", "profile", "config"],
+		examples: ["pi-space list", "pi-space list work", "pi-space list --every"],
+	},
+	new: {
+		summary: "create a space",
+		usage: "new <name>",
+		about: ["Its settings.json declares the extension. It runs the setup command in it when there is one, and does not start Pi."],
+		args: [["<name>", "the name of the new space"]],
+		options: [],
+		calls: ["dir", "setup", "profile", "config"],
+		examples: ["pi-space new work", "pi-space --setup 'my-launcher --home {home} setup' new work"],
+	},
+	setup: {
+		summary: "run the setup command in a space",
+		usage: "setup <name|--every>",
+		about: ["It needs a setup command: --setup or $PI_SPACES_SETUP. It never runs in base."],
+		args: [
+			["<name>", "a space"],
+			["--every", "every space, never base; a failure does not stop the rest, and the exit status is 1 if any failed"],
+		],
+		options: [],
+		calls: ["dir", "setup", "profile", "config"],
+		examples: ["pi-space setup work", "pi-space setup --every", "pi-space --setup 'my-launcher --home {home} setup' setup --every"],
+	},
+	rename: {
+		summary: "rename a space",
+		usage: "rename <old> <new>",
+		about: ["It refuses what remove refuses: base, the space you are in, and a space that holds the base home."],
+		args: [
+			["<old>", "the space to rename"],
+			["<new>", "its new name"],
+		],
+		options: [],
+		calls: ["dir", "profile", "config"],
+		examples: ["pi-space rename work client"],
+	},
+	remove: {
+		summary: "delete a space, keeping a backup",
+		usage: "remove <name> [--yes|-y] [--no-backup]",
+		about: ["It deletes the space and everything in it, after asking, and keeps a backup in .backups unless told not to."],
+		args: [["<name>", "the space to delete"]],
+		options: [
+			{ flag: "--yes", alias: "-y", text: "do not ask; keep a backup" },
+			{ flag: "--no-backup", text: "delete without a backup" },
+		],
+		calls: ["dir", "profile", "config"],
+		examples: ["pi-space remove work", "pi-space remove work --yes", "pi-space remove work --yes --no-backup"],
+	},
+	update: {
+		summary: "update the packages of a space",
+		usage: "update <name|--every> [pi args...]",
+		about: ["It runs Pi's update in a space, or in base and then every space."],
+		args: [...NAME_OR_EVERY, PI_ARGS],
+		options: [],
+		calls: ["command", "dir", "profile", "config"],
+		examples: ["pi-space update work", "pi-space update base --extensions", "pi-space --command 'my-launcher --' update --every"],
+	},
+	install: {
+		summary: "install a package in a space",
+		usage: "install <name|--every> <source> [pi args...]",
+		about: ["It runs Pi's install in a space, or in base and then every space."],
+		args: [...NAME_OR_EVERY, ["<source>", "the package to install, e.g. npm:some-package"], PI_ARGS],
+		options: [],
+		calls: ["command", "dir", "profile", "config"],
+		examples: ["pi-space install work npm:some-package", "pi-space install --every npm:some-package"],
+	},
+	uninstall: {
+		summary: "remove a package from a space",
+		usage: "uninstall <name|--every> <source> [pi args...]",
+		about: ["It runs Pi's uninstall (its alias of remove) in a space, or in base and then every space."],
+		args: [...NAME_OR_EVERY, ["<source>", "the package to remove, e.g. npm:some-package"], PI_ARGS],
+		options: [],
+		calls: ["command", "dir", "profile", "config"],
+		examples: ["pi-space uninstall work npm:some-package", "pi-space uninstall --every npm:some-package"],
+	},
+	completion: {
+		summary: "print the shell completion script",
+		usage: "completion <shell>",
+		about: ["Supported shells: zsh."],
+		args: [["<shell>", "zsh"]],
+		options: [],
+		calls: [],
+		examples: ["pi-space completion zsh", "source <(pi-space completion zsh)"],
+	},
+};
+
+const HELP_OPTION = { flag: "--help", alias: "-h", text: "the help of this command" };
+
+/** The help of one command: usage, what it does, arguments, options, the call options that apply, and examples. */
+function commandHelp(name        )         {
+	const help = COMMANDS[name];
+	const options = [...help.options, HELP_OPTION].map((option)                   => [option.alias ? `${option.flag}, ${option.alias}` : option.flag, option.text]);
+	const calls = help.calls.map((call)                   => CALL_HELP[call]);
+	const width = Math.max(...[...help.args, ...options, ...calls].map(([label]) => label.length)) + 2;
+	const rows = (list                    ) => list.map(([label, text]) => `  ${label.padEnd(width)}${text}`);
+	const sections             = [
+		[`Usage: pi-space ${help.usage}`],
+		[`${help.summary[0].toUpperCase()}${help.summary.slice(1)}.`, ...help.about],
+		["Arguments:", ...rows(help.args)],
+		["Options:", ...rows(options)],
+		...(calls.length > 0 ? [["Call options (before the command, for this call only):", ...rows(calls)]] : []),
+		["Examples:", ...help.examples.map((example) => `  ${example}`)],
+	];
+	return `${sections.map((section) => section.join("\n")).join("\n\n")}\n`;
+}
+
 /**
  * The call options (--command, --dir, --setup, --profile, --config) come first; after a space name every argument belongs to Pi.
  * The commands (list, new, setup, remove, rename, update, install, uninstall, completion) are reserved words, so they
@@ -134,10 +284,12 @@ export function parseCli(args          )             {
 function parseCommand(args          )             {
 	const [first, ...rest] = args;
 	if (first === undefined) return { kind: "picker" };
-	if (first === "--help" || first === "-h") return { kind: "help" };
+	if (isHelpFlag(first)) return rest.length === 0 ? { kind: "help" } : rest.length === 1 ? { kind: "command-help", command: rest[0] } : { kind: "usage" };
 	if (first === "--version" || first === "-v") return { kind: "version" };
 	if (Object.hasOwn(REPLACED, first)) return { kind: "replaced", option: first, instead: REPLACED[first                         ] };
 	if (first.startsWith("-")) return { kind: "unknown-option", option: first };
+	// --help after a command word is that command's help; after a space name it belongs to Pi (the launch below).
+	if (Object.hasOwn(COMMANDS, first) && rest.some(isHelpFlag)) return { kind: "command-help", command: first };
 	if (first === "list" && rest.length === 0) return { kind: "list" };
 	if (PACKAGE_VERBS.includes(first)) return parsePackages(first               , rest);
 	if (first === "new") return rest.length === 1 ? { kind: "new", name: rest[0] } : { kind: "usage" };
@@ -386,6 +538,13 @@ export async function main(argv          , io       )                {
 		case "help":
 			io.stdout.write(USAGE);
 			return io.exit(0);
+		case "command-help":
+			if (Object.hasOwn(COMMANDS, command.command)) {
+				io.stdout.write(commandHelp(command.command));
+				return io.exit(0);
+			}
+			io.stderr.write(`pi-space: No help for "${command.command}"; commands: ${Object.keys(COMMANDS).join(", ")}.\n`);
+			return io.exit(2);
 		case "version":
 			io.stdout.write(`${VERSION}\n`);
 			return io.exit(0);
@@ -458,28 +617,57 @@ function printCompletion(shell                    , io       )       {
 const FILES = "__files__";
 
 /**
- * The zsh script: it asks `pi-space __complete <the words before the cursor>` for candidates, one per line,
- * and falls back to the shell's file completion on the marker. An abbreviation or alias has already expanded
- * by then, so `my-space <TAB>` completes the words of what it stands for.
+ * The zsh script: it asks `pi-space __complete <the words before the cursor>` for candidates, one per line as
+ * `<group>\t<value>\t<description>`, and hands each group to _describe (a ":" in a value is escaped for it).
+ * The `__files__` marker falls back to the shell's file completion. An abbreviation or alias has already
+ * expanded by then, so `my-space <TAB>` completes the words of what it stands for.
+ * The options show only for a word that starts with "-", so `pi-space new <TAB>` never inserts a lone --help.
  */
 const ZSH_COMPLETION = [
 	"#compdef pi-space",
 	"# zsh completion for pi-space. Load it from .zshrc with: source <(pi-space completion zsh)",
 	"_pi_space() {",
-	"  local -a lines",
+	"  local -a lines cmds spaces profiles shells opts",
+	"  local line group value text ret=1",
 	'  lines=("${(@f)$(command "${words[1]}" __complete "${(@)words[2,CURRENT-1]}" 2>/dev/null)}")',
 	`  if [[ "\${lines[1]}" == ${FILES} ]]; then`,
 	"    _files",
 	"    return",
 	"  fi",
-	'  lines=("${(@)lines:#}")',
-	"  compadd -a lines",
+	'  for line in "${(@)lines}"; do',
+	'    [[ -n "$line" ]] || continue',
+	"    group=${line%%$'\\t'*}",
+	"    line=${line#*$'\\t'}",
+	"    value=${line%%$'\\t'*}",
+	"    text=${line#*$'\\t'}",
+	"    [[ \"$text\" == \"$line\" ]] && text=",
+	"    value=${value//:/\\\\:}",
+	'    case "$group" in',
+	'      command) cmds+=("$value:$text") ;;',
+	'      space) spaces+=("$value:$text") ;;',
+	'      profile) profiles+=("$value:$text") ;;',
+	'      shell) shells+=("$value:$text") ;;',
+	'      option) [[ "$PREFIX" == -* ]] && opts+=("$value:$text") ;;',
+	"    esac",
+	"  done",
+	"  (( $#cmds )) && _describe -t commands 'command' cmds && ret=0",
+	"  (( $#spaces )) && _describe -t spaces 'space' spaces && ret=0",
+	"  (( $#profiles )) && _describe -t profiles 'profile' profiles && ret=0",
+	"  (( $#shells )) && _describe -t shells 'shell' shells && ret=0",
+	"  (( $#opts )) && _describe -t options 'option' opts && ret=0",
+	"  return ret",
 	"}",
 	"compdef _pi_space pi-space",
 	"",
 ].join("\n");
 
-const COMMAND_WORDS = ["list", "new", "setup", "rename", "remove", "update", "install", "uninstall", "completion"];
+/** The groups of a `__complete` line. */
+                                                                  
+
+/** One `__complete` line; the description never holds a tab or a newline. */
+function candidate(group       , value        , text        )         {
+	return `${group}\t${value}\t${text.replace(/\s+/g, " ")}`;
+}
 
 /**
  * The hidden `__complete <words before the cursor>`: one candidate per line, honoring the call options already
@@ -496,6 +684,49 @@ function complete(words          , io       )       {
 	return io.exit(0);
 }
 
+/** The first-place commands: `completion` is left out (it still works typed in full). */
+function commandCandidates()           {
+	return Object.entries(COMMANDS)
+		.filter(([name]) => name !== "completion")
+		.map(([name, help]) => candidate("command", name, help.summary));
+}
+
+/** The call options not typed yet, then --help and --version when nothing was typed before. */
+function firstOptions(call             , alone         )           {
+	const calls = Object.entries(CALL_OPTIONS)
+		.filter(([, key]) => call[key] === undefined)
+		.map(([flag, key]) => candidate("option", flag, CALL_HELP[key][1]));
+	const general = alone ? [candidate("option", "--help", "print the help"), candidate("option", "--version", "print the version")] : [];
+	return [...calls, ...general];
+}
+
+/** `base`, if asked, then the spaces. */
+function spaceCandidates(spaces          , withBase         )           {
+	return [...(withBase ? [candidate("space", BASE, "the home Pi starts with")] : []), ...spaces.map((name) => candidate("space", name, "space"))];
+}
+
+/** What follows a command word: its target, its own options and --help. */
+function commandArguments(command        , spaces          )           {
+	const every = (text        ) => candidate("space", "--every", text);
+	const options = [...COMMANDS[command].options, HELP_OPTION].map((option) => candidate("option", option.flag, option.text));
+	switch (command) {
+		case "remove":
+		case "rename":
+			return [...spaceCandidates(spaces, false), ...options];
+		case "setup":
+			return [...spaceCandidates(spaces, false), every("every space"), ...options];
+		case "list":
+		case "update":
+		case "install":
+		case "uninstall":
+			return [...spaceCandidates(spaces, true), every("every space (base first)"), ...options];
+		case "completion":
+			return [...SHELLS.map((shell) => candidate("shell", shell, `the ${shell} completion script`)), ...options];
+		default:
+			return options;
+	}
+}
+
 function candidates(words          , io       )           {
 	const call              = {};
 	let index = 0;
@@ -509,33 +740,30 @@ function candidates(words          , io       )           {
 	const { dir } = resolveSettings(call, io);
 	const rest = words.slice(index);
 	const spaces = listSpaces(dir);
-	if (rest.length === 0) return [...COMMAND_WORDS, BASE, ...spaces];
-	if (rest.length > 1) return [];
-	switch (rest[0]) {
-		case "remove":
-		case "rename":
-			return spaces;
-		case "setup":
-			return [...spaces, "--every"];
-		case "list":
-		case "update":
-		case "install":
-		case "uninstall":
-			return [BASE, ...spaces, "--every"];
-		case "completion":
-			return SHELLS;
-		default:
-			return [];
-	}
+	if (rest.length === 0) return [...commandCandidates(), ...spaceCandidates(spaces, true), ...firstOptions(call, index === 0)];
+	if (rest.length > 1 || !Object.hasOwn(COMMANDS, rest[0])) return [];
+	return commandArguments(rest[0], spaces);
 }
 
-/** The candidates for the value of a call option: profile names, the shell's files for a path, nothing for a command. */
+/** The candidates for the value of a call option: profile names with their command, the shell's files for a path, nothing for a command. */
 function optionValues(option                           , call             , io       )           {
-	if (option === "--profile") return profileNames(resolveSettings(call, io).config);
+	if (option === "--profile") {
+		const { config } = resolveSettings(call, io);
+		return profileNames(config).map((name) => candidate("profile", name, profileText(config, name, io)));
+	}
 	if (option === "--config" || option === "--dir") return [FILES];
 	return [];
 }
 
+/** A profile's command, else "profile". */
+function profileText(config                    , name        , io       )         {
+	try {
+		return profileByName(config, name, io.env, io.home).command || "profile";
+	} catch {
+		return "profile";
+	}
+}
+
 /** Prints the reason and returns false when the setup command has an unclosed quote. */
 function checkSetup(io       , source        )          {
 	try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jals1212/pi-spaces-cli",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "The pi-space command: pick a space and start Pi in it. Companion to the Pi extension @jals1212/pi-spaces.",
   "license": "MIT",
   "author": "jals1212",