feat: single command mode (#25)

* feat: infer `single` from `name` parsing

* chore: replace `&&` chain w/ `if` block

* feat: add `isOne` param for fallback assertion

* fix: prevent `command()` calls with “single” enabled

* chore: reuse `isOne` parameter

* fix: only include `--version` flag on default/root help

* chore: fix tests for `—version` move;

- also, `util.help` was mutating; expectant saved duplicate output!

* chore: add `util.help` test for single output

* chore: update README for single-command mode

Author: lukeed

lib/index.js

@@ -5,21 +5,28 @@ const ALL = '__all__';
 const DEF = '__default__';
 
 class Sade {
-	constructor(name) {
+	constructor(name, isOne) {
+		let [bin, ...rest] = name.split(/\s+/);
+		isOne = isOne || rest.length > 0;
+
 		this.tree = {};
-		this.name = name;
-		this.ver = '0.0.0';
+		this.name = bin;
 		this.default = '';
+		this.ver = '0.0.0';
 		// set internal shapes;
 		this.command(ALL);
-		this.command(`${DEF} <command>`)
-			.option('-v, --version', 'Displays current version');
+		this.command([DEF].concat(isOne ? rest : '<command>').join(' '));
+		this.single = isOne;
 		this.curr = ''; // reset
 	}
 
 	command(str, desc, opts={}) {
-		let cmd=[], usage=[], rgx=/(\[|<)/;
+		if (this.single) {
+			throw new Error('Disable "single" mode to add commands');
+		}
+
 		// All non-([|<) are commands
+		let cmd=[], usage=[], rgx=/(\[|<)/;
 		str.split(/\s+/).forEach(x => {
 			(rgx.test(x.charAt(0)) ? usage : cmd).push(x);
 		});
@@ -31,12 +38,13 @@ class Sade {
 			throw new Error(`Command already exists: ${cmd}`);
 		}
 
+		// re-include `cmd` for commands
+		cmd.includes('__') || usage.unshift(cmd);
+		usage = usage.join(' '); // to string
+
 		this.curr = cmd;
 		if (opts.default) this.default=cmd;
 
-		!~cmd.indexOf('__') && usage.unshift(cmd); // re-include `cmd`
-		usage = usage.join(' '); // to string
-
 		this.tree[cmd] = { usage, options:[], alias:{}, default:{}, examples:[] };
 		if (desc) this.describe(desc);
 
@@ -52,7 +60,7 @@ class Sade {
 		let cmd = this.tree[ this.curr || ALL ];
 
 		let [flag, alias] = $.parse(str);
-		(alias && alias.length > 1) && ([flag, alias]=[alias, flag]);
+		if (alias && alias.length > 1) [flag, alias]=[alias, flag];
 
 		str = `--${flag}`;
 		if (alias && alias.length > 0) {
@@ -91,41 +99,43 @@ class Sade {
 		let offset = 2; // argv slicer
 		let alias = { h:'help', v:'version' };
 		let argv = mri(arr.slice(offset), { alias });
+		let isSingle = this.single;
 		let bin = this.name;
-
-		// Loop thru possible command(s)
-		let tmp, name='';
-		let i=1, len=argv._.length + 1;
-		for (; i < len; i++) {
-			tmp = argv._.slice(0, i).join(' ');
-			if (this.tree[tmp] !== void 0) {
-				name=tmp; offset=(i + 2); // argv slicer
+		let tmp, name = '';
+		let isVoid, cmd;
+
+		if (isSingle) {
+			cmd = this.tree[DEF];
+		} else {
+			// Loop thru possible command(s)
+			let i=1, len=argv._.length + 1;
+			for (; i < len; i++) {
+				tmp = argv._.slice(0, i).join(' ');
+				if (this.tree[tmp] !== void 0) {
+					name=tmp; offset=(i + 2); // argv slicer
+				}
 			}
-		}
-
-		let cmd = this.tree[name];
-		let isVoid = (cmd === void 0);
-
-		if (isVoid) {
-			if (this.default) {
-				name = this.default;
-				cmd = this.tree[name];
-				arr.unshift(name);
-				offset++;
-			} else if (tmp) {
-				return $.error(bin, `Invalid command: ${tmp}`);
-			} //=> else: cmd not specified, wait for now...
-		}
 
-		if (argv.version) {
-			return console.log(`${bin}, ${this.ver}`);
+			cmd = this.tree[name];
+			isVoid = (cmd === void 0);
+
+			if (isVoid) {
+				if (this.default) {
+					name = this.default;
+					cmd = this.tree[name];
+					arr.unshift(name);
+					offset++;
+				} else if (tmp) {
+					return $.error(bin, `Invalid command: ${tmp}`);
+				} //=> else: cmd not specified, wait for now...
+			}
 		}
 
-		if (argv.help) {
-			return this.help(!isVoid && name);
-		}
+		// show main help if relied on "default" for multi-cmd
+		if (argv.help) return this.help(!isSingle && !isVoid && name);
+		if (argv.version) return this._version();
 
-		if (cmd === void 0) {
+		if (!isSingle && cmd === void 0) {
 			return $.error(bin, 'No command specified.');
 		}
 
@@ -144,7 +154,7 @@ class Sade {
 		let args = vals._.splice(0, reqs.length);
 
 		if (args.length < reqs.length) {
-			name && (bin += ` ${name}`); // for help text
+			if (name) bin += ` ${name}`; // for help text
 			return $.error(bin, 'Insufficient arguments!');
 		}
 
@@ -159,9 +169,13 @@ class Sade {
 
 	help(str) {
 		console.log(
-			$.help(this.name, this.tree, str || DEF)
+			$.help(this.name, this.tree, str || DEF, this.single)
 		);
 	}
+
+	_version() {
+		console.log(`${this.name}, ${this.ver}`);
+	}
 }
 
-module.exports = str => new Sade(str);
+module.exports = (str, isOne) => new Sade(str, isOne);

lib/utils.js

@@ -36,22 +36,23 @@ function section(str, arr, fn) {
 	return out + NL;
 }
 
-exports.help = function (bin, tree, key) {
+exports.help = function (bin, tree, key, single) {
 	let out='', cmd=tree[key], pfx=`$ ${bin}`, all=tree[ALL];
-	let prefix = s => `${pfx} ${s}`;
+	let prefix = s => `${pfx} ${s}`.replace(/\s+/g, ' ');
 
 	// update ALL & CMD options
-	all.options.push(['-h, --help', 'Displays this message']);
-	cmd.options = (cmd.options || []).concat(all.options);
+	let tail = [['-h, --help', 'Displays this message']];
+	if (key === DEF) tail.unshift(['-v, --version', 'Displays current version']);
+	cmd.options = (cmd.options || []).concat(all.options, tail);
 
 	// write options placeholder
-	(cmd.options.length > 0) && (cmd.usage += ' [options]');
+	if (cmd.options.length > 0) cmd.usage += ' [options]';
 
 	// description ~> text only; usage ~> prefixed
 	out += section('Description', cmd.describe, noop);
 	out += section('Usage', [cmd.usage], prefix);
 
-	if (key === DEF) {
+	if (!single && key === DEF) {
 		// General help :: print all non-internal commands & their 1st line of text
 		let cmds = Object.keys(tree).filter(k => !/__/.test(k));
 		let text = cmds.map(k => [k, (tree[k].describe || [''])[0]]);

readme.md

@@ -141,16 +141,94 @@ prog
 ```
 
 
+## Single Command Mode
+
+In certain circumstances, you may only need `sade` for a single-command CLI application.
+
+> **Note:** Until `v1.6.0`, this made for an awkward pairing.
+
+To enable this, you may make use of the [`isSingle`](#issingle) argument. Doing so allows you to pass the program's entire [`usage` text](#usage-1) into the `name` argument.
+
+With "Single Command Mode" enabled, your entire binary operates as one command. This means that any [`prog.command`](#progcommandusage-desc-opts) calls are disallowed & will instead throw an Error. Of course, you may still define a program version, a description, an example or two, and declare options. You are customizing the program's attributes as a whole.<sup>*</sup>
+
+> <sup>*</sup> This is true for multi-command applications, too, up until your first `prog.command()` call!
+
+***Example***
+
+Let's reconstruct [`sirv-cli`](https://github.com/lukeed/sirv), which is a single-command application that (optionally) accepts a directory from which to serve files. It also offers a slew of option flags:
+
+```js
+sade('sirv [dir]', true)
+  .version('1.0.0')
+  .describe('Run a static file server')
+  .example('public -qeim 31536000')
+  .example('--port 8080 --etag')
+  .example('my-app --dev')
+  .option('-D, --dev', 'Enable "dev" mode')
+  .option('-e, --etag', 'Enable "Etag" header')
+  // There are a lot...
+  .option('-H, --host', 'Hostname to bind', 'localhost')
+  .option('-p, --port', 'Port to bind', 5000)
+  .action((dir, opts) => {
+    // Program handler
+  })
+  .parse(process.argv);
+```
+
+When `sirv --help` is run, the generated help text is trimmed, fully aware that there's only one command in this program:
+
+```
+  Description
+    Run a static file server
+
+  Usage
+    $ sirv [dir] [options]
+
+  Options
+    -D, --dev        Enable "dev" mode
+    -e, --etag       Enable "Etag" header
+    -H, --host       Hostname to bind  (default localhost)
+    -p, --port       Port to bind  (default 5000)
+    -v, --version    Displays current version
+    -h, --help       Displays this message
+
+  Examples
+    $ sirv public -qeim 31536000
+    $ sirv --port 8080 --etag
+    $ sirv my-app --dev
+```
+
+
+
 ## API
 
-### sade(name)
+### sade(name, isSingle)
+Returns: `Program`
+
+Returns your chainable Sade instance, aka your `Program`.
 
 #### name
-
 Type: `String`<br>
-Returns: `Program`
+Required: `true`
+
+The name of your `Program` / binary application.
+
+#### isSingle
+Type: `Boolean`<br>
+Default: `name.includes(' ');`
+
+If your `Program` is meant to have ***only one command***.<br>
+When `true`, this simplifies your generated `--help` output such that:
+
+* the "root-level help" is your _only_ help text
+* the "root-level help" does not display an `Available Commands` section
+* the "root-level help" does not inject `$ name <command>` into the `Usage` section
+* the "root-level help" does not display `For more info, run any command with the `--help` flag` text
+
+You may customize the `Usage` of your command by modifying the `name` argument directly.<br>
+Please read [Single Command Mode](#single-command-mode) for an example and more information.
 
-The name of your bin/program. Returns the `Program` itself, wherein all other methods are available.
+> **Important:** Whenever `name` includes a custom usage, then `isSingle` is automatically assumed and enforced!
 
 ### prog.command(usage, desc, opts)
 

test/fixtures/single1.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+const sade = require('../../lib');
+
+sade('bin <type> [dir]')
+	.describe('hello description')
+	.option('-g, --global', 'flag 1')
+	.action((type, dir, opts) => {
+		dir = dir || '~default~';
+		console.log(`~> ran "single" w/ "${type}" and "${dir}" values`);
+	})
+	.parse(process.argv);

test/fixtures/single2.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+const sade = require('../../lib');
+
+sade('bin', true)
+	.describe('hello description')
+	.option('-g, --global', 'flag 1')
+	.action(opts => {
+		console.log(`~> ran "single" with: ${JSON.stringify(opts)}`);
+	})
+	.parse(process.argv);

test/fixtures/single3.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+const sade = require('../../lib');
+
+sade('bin', true)
+	.command('foo <bar>')
+	.action((bar, opts) => {
+		console.log(`~> ran "foo" with: ${JSON.stringify(opts)}`);
+	})
+	.parse(process.argv);

test/index.js

@@ -27,9 +27,6 @@ test('sade()', t => {
 	for (k in ctx.tree) {
 		isShapely(t, ctx.tree, k);
 	}
-	let obj = ctx.tree.__default__;
-	t.deepEqual(obj.alias, { v:['version'] }, 'add `-v, --version` alias');
-	t.deepEqual(obj.options[0], ['-v, --version', 'Displays current version'], 'add `-v, --version` flag');
 	t.end();
 });
 
@@ -215,7 +212,7 @@ test('prog.action (multi optional)', t => {
 	(c=true) && run(); // +4 tests
 });
 
-test('parse lazy', t => {
+test('prog.parse :: lazy', t => {
 	t.plan(14);
 
 	let val='aaa', f=false;
@@ -248,3 +245,35 @@ test('parse lazy', t => {
 
 	bar.handler.apply(null, bar.args); // manual bcuz lazy; +2 tests
 });
+
+test('prog.parse :: lazy :: single', t => {
+	t.plan(14);
+
+	let val='aaa', f=false;
+
+	let ctx = sade('foo <src>').option('--force').action((src, opts) => {
+		t.is(src, val, '~> receives `src` param first');
+		f && t.ok(opts.force, '~> receives the `force` flag (true) when parsed');
+	});
+
+	let run = _ => ctx.parse(['', '', val, f && '--force'], { lazy:true });
+
+	let foo = run();
+	t.is(foo.constructor, Object, 'returns an object');
+	t.same(Object.keys(foo), ['args', 'name', 'handler'], 'contains `args`,`name`,`handler` keys');
+	t.ok(Array.isArray(foo.args), '~> returns the array of arguments');
+	t.is(foo.args[0], val, '~> preserves the `src` value first');
+	t.is(foo.args[1].constructor, Object, '~> preserves the `opts` value last');
+	t.ok(Array.isArray(foo.args[1]._), '~> ensures `opts._` is still `[]` at least');
+	t.is(typeof foo.handler, 'function', '~> returns the action handler');
+	t.is(foo.name, '', '~> returns empty command name');
+
+	foo.handler.apply(null, foo.args); // must be manual bcuz lazy; +1 test
+
+	let bar = run(f=true);
+	t.is(bar.constructor, Object, 'returns an object');
+	t.is(bar.args[1].constructor, Object, '~> preserves the `opts` value last');
+	t.is(bar.args[1].force, true, '~> attaches the `force:true` option');
+
+	bar.handler.apply(null, bar.args); // manual bcuz lazy; +2 tests
+});