clap-ts 0.3.0 → 0.4.0

package/src/__tests__/plugins.test.ts

@@ -0,0 +1,182 @@
+/**
+ * Tests for discovering subcommands from installed packages.
+ */
+
+import { describe, test, expect, afterEach, beforeEach } from 'bun:test';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import {
+  discoverPlugins,
+  pluginSubCommands,
+  nodeModulesPaths,
+} from '../plugins.js';
+import type { DiscoveredPlugin } from '../plugins.js';
+import { defineCommand } from '../runner.js';
+import { runCli, captureArgs } from '../testing.js';
+import type { CommandDef } from '../types.js';
+
+let dir: string;
+
+function makePackage(root: string, name: string, description?: string): void {
+  const target = join(root, 'node_modules', name);
+  mkdirSync(target, { recursive: true });
+  writeFileSync(
+    join(target, 'package.json'),
+    JSON.stringify({ name, version: '1.0.0', ...(description === undefined ? {} : { description }) }),
+  );
+}
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'clap-ts-plugins-'));
+});
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe('nodeModulesPaths', () => {
+  test('walks up to the root', () => {
+    const paths = nodeModulesPaths('/a/b/c');
+    expect(paths[0]).toBe(join('/a/b/c', 'node_modules'));
+    expect(paths).toContain(join('/a', 'node_modules'));
+  });
+});
+
+describe('discoverPlugins', () => {
+  test('finds packages matching the prefix', () => {
+    makePackage(dir, 'demo-plugin-deploy');
+    makePackage(dir, 'demo-plugin-build');
+    makePackage(dir, 'unrelated');
+    const found = discoverPlugins('demo', { searchPaths: [join(dir, 'node_modules')] });
+    expect(found.map((p) => p.name)).toEqual(['build', 'deploy']);
+  });
+
+  test('handles scoped packages', () => {
+    makePackage(dir, '@acme/demo-plugin-ship');
+    const found = discoverPlugins('demo', { searchPaths: [join(dir, 'node_modules')] });
+    expect(found).toHaveLength(1);
+    expect(found[0]!.name).toBe('ship');
+    expect(found[0]!.packageName).toBe('@acme/demo-plugin-ship');
+  });
+
+  test('ignores a bare prefix with nothing after it', () => {
+    makePackage(dir, 'demo-plugin-');
+    expect(discoverPlugins('demo', { searchPaths: [join(dir, 'node_modules')] })).toEqual([]);
+  });
+
+  test('a missing search path is not an error', () => {
+    expect(discoverPlugins('demo', { searchPaths: [join(dir, 'nope')] })).toEqual([]);
+  });
+
+  test('the nearest copy shadows one further up', () => {
+    const near = join(dir, 'near');
+    const far = join(dir, 'far');
+    makePackage(near, 'demo-plugin-x');
+    makePackage(far, 'demo-plugin-x');
+    const found = discoverPlugins('demo', {
+      searchPaths: [join(near, 'node_modules'), join(far, 'node_modules')],
+    });
+    expect(found).toHaveLength(1);
+    expect(found[0]!.dir).toContain('near');
+  });
+
+  test('the prefix is configurable', () => {
+    makePackage(dir, 'demo-ext-thing');
+    const found = discoverPlugins('demo', {
+      prefix: 'demo-ext-',
+      searchPaths: [join(dir, 'node_modules')],
+    });
+    expect(found.map((p) => p.name)).toEqual(['thing']);
+  });
+});
+
+describe('pluginSubCommands', () => {
+  function withStub(load: (p: DiscoveredPlugin) => CommandDef<any> | undefined) {
+    makePackage(dir, 'demo-plugin-deploy', 'Ship it');
+    return pluginSubCommands('demo', { searchPaths: [join(dir, 'node_modules')], load });
+  }
+
+  test('names the subcommand after the package suffix', () => {
+    const thunk = withStub(() => ({ meta: { name: 'ignored' }, run() {} }));
+    expect(Object.keys(thunk())).toEqual(['deploy']);
+    expect(thunk()['deploy']!.meta.name).toBe('deploy');
+  });
+
+  test("falls back to the package description for help", () => {
+    const thunk = withStub(() => ({ meta: { name: 'x' }, run() {} }));
+    expect(thunk()['deploy']!.meta.description).toBe('Ship it');
+  });
+
+  test("a plugin's own description wins", () => {
+    const thunk = withStub(() => ({ meta: { name: 'x', description: 'Own' }, run() {} }));
+    expect(thunk()['deploy']!.meta.description).toBe('Own');
+  });
+
+  test('a plugin exporting nothing usable is skipped', () => {
+    expect(Object.keys(withStub(() => undefined)())).toEqual([]);
+  });
+
+  test('a failing plugin names itself in the error', () => {
+    const thunk = withStub(() => {
+      throw new Error('boom');
+    });
+    expect(() => thunk()).toThrow("plugin 'demo-plugin-deploy' failed to load: boom");
+  });
+
+  test('onError can downgrade a failure to a skip', () => {
+    const seen: string[] = [];
+    makePackage(dir, 'demo-plugin-deploy');
+    const thunk = pluginSubCommands('demo', {
+      searchPaths: [join(dir, 'node_modules')],
+      load: () => {
+        throw new Error('boom');
+      },
+      onError: (plugin) => seen.push(plugin.name),
+    });
+    expect(Object.keys(thunk())).toEqual([]);
+    expect(seen).toEqual(['deploy']);
+  });
+});
+
+describe('plugins as lazy subcommands', () => {
+  test('discovery is deferred until a token could be a subcommand', async () => {
+    makePackage(dir, 'demo-plugin-deploy');
+    let loads = 0;
+    const main = defineCommand({
+      meta: { name: 'demo', version: '1.0' },
+      args: { verbose: { type: 'boolean' } },
+      run() {},
+      lazySubCommands: pluginSubCommands('demo', {
+        searchPaths: [join(dir, 'node_modules')],
+        load: () => {
+          loads++;
+          return { meta: { name: 'x' }, run() {} };
+        },
+      }),
+    });
+
+    await runCli(main, ['--verbose']);
+    expect(loads).toBe(0);
+
+    await runCli(main, ['deploy']);
+    expect(loads).toBe(1);
+  });
+
+  test('a discovered plugin runs and parses its own args', async () => {
+    makePackage(dir, 'demo-plugin-deploy');
+    const main = defineCommand({
+      meta: { name: 'demo' },
+      lazySubCommands: pluginSubCommands('demo', {
+        searchPaths: [join(dir, 'node_modules')],
+        load: () => ({
+          meta: { name: 'x' },
+          args: { target: { type: 'string' } },
+          run() {},
+        }),
+      }),
+    });
+
+    const { args } = await captureArgs(main, ['deploy', '--target', 'prod']);
+    expect(args['target']).toBe('prod');
+  });
+});

package/src/__tests__/progress.test.ts

@@ -0,0 +1,221 @@
+/**
+ * Tests for spinners and progress bars, including that they stay quiet when
+ * the destination is not a terminal.
+ */
+
+import { describe, test, expect } from 'bun:test';
+import { spinner, progressBar } from '../progress.js';
+import type { OutputSink } from '../types.js';
+
+function collector(): OutputSink & { text(): string } {
+  const chunks: string[] = [];
+  return {
+    write(chunk: string) {
+      chunks.push(chunk);
+    },
+    text: () => chunks.join(''),
+  };
+}
+
+const off = { enabled: false as const, color: false };
+const on = { enabled: true as const, color: false, interval: 10_000 };
+
+describe('spinner when nothing is watching', () => {
+  test('start and update draw nothing', () => {
+    const sink = collector();
+    spinner('working', { sink, ...off }).start().update('still working');
+    expect(sink.text()).toBe('');
+  });
+
+  test('succeed still reports once', () => {
+    const sink = collector();
+    spinner('working', { sink, ...off }).start().succeed('done');
+    expect(sink.text()).toBe('✔ done\n');
+  });
+
+  test('fail and warn use their own marks', () => {
+    const failed = collector();
+    spinner('', { sink: failed, ...off }).fail('bad');
+    expect(failed.text()).toBe('✖ bad\n');
+
+    const warned = collector();
+    spinner('', { sink: warned, ...off }).warn('careful');
+    expect(warned.text()).toBe('⚠ careful\n');
+  });
+
+  test('stop leaves nothing behind', () => {
+    const sink = collector();
+    spinner('working', { sink, ...off }).start().stop();
+    expect(sink.text()).toBe('');
+  });
+
+  test('an empty message prints no line at all', () => {
+    const sink = collector();
+    spinner('', { sink, ...off }).succeed();
+    expect(sink.text()).toBe('');
+  });
+
+  test('enabled reports the decision', () => {
+    expect(spinner('x', { sink: collector(), ...off }).enabled).toBe(false);
+    expect(spinner('x', { sink: collector(), ...on }).enabled).toBe(true);
+  });
+});
+
+describe('spinner when drawing', () => {
+  test('start draws a frame and the message', () => {
+    const sink = collector();
+    const spin = spinner('working', { sink, ...on }).start();
+    expect(sink.text()).toContain('working');
+    expect(sink.text()).toContain('\r\x1b[2K');
+    spin.stop();
+  });
+
+  test('ascii mode avoids braille frames', () => {
+    const sink = collector();
+    spinner('working', { sink, ...on, ascii: true }).start().stop();
+    expect(sink.text()).not.toMatch(/[⠋⠙⠹]/);
+  });
+
+  test('succeed clears the line before reporting', () => {
+    const sink = collector();
+    spinner('working', { sink, ...on }).start().succeed('done');
+    expect(sink.text().endsWith('✔ done\n')).toBe(true);
+  });
+});
+
+describe('progressBar', () => {
+  test('render reflects the position', () => {
+    const bar = progressBar({ total: 10, width: 10, sink: collector(), ...off });
+    expect(bar.render()).toContain('  0% 0/10');
+    bar.update(5);
+    expect(bar.render()).toContain(' 50% 5/10');
+    expect(bar.render()).toContain('█████░░░░░');
+  });
+
+  test('tick moves forward', () => {
+    const bar = progressBar({ total: 4, width: 4, sink: collector(), ...off });
+    bar.tick().tick(2);
+    expect(bar.render()).toContain('3/4');
+  });
+
+  test('the position is clamped at both ends', () => {
+    const bar = progressBar({ total: 5, width: 5, sink: collector(), ...off });
+    bar.update(-3);
+    expect(bar.render()).toContain('0/5');
+    bar.update(99);
+    expect(bar.render()).toContain('5/5');
+  });
+
+  test('a label is appended', () => {
+    const bar = progressBar({ total: 2, width: 2, text: 'files', sink: collector(), ...off });
+    expect(bar.render()).toContain('files');
+    bar.update(1, 'more files');
+    expect(bar.render()).toContain('more files');
+  });
+
+  test('nothing is drawn when disabled', () => {
+    const sink = collector();
+    progressBar({ total: 3, sink, ...off }).update(1).tick();
+    expect(sink.text()).toBe('');
+  });
+
+  test('finish reports the label once when disabled', () => {
+    const sink = collector();
+    progressBar({ total: 3, sink, ...off }).finish('all done');
+    expect(sink.text()).toBe('all done\n');
+  });
+
+  test('finish fills the bar and ends the line when drawing', () => {
+    const sink = collector();
+    const bar = progressBar({ total: 3, width: 3, sink, ...on });
+    bar.finish();
+    expect(bar.render()).toContain('100% 3/3');
+    expect(sink.text().endsWith('\n')).toBe(true);
+  });
+
+  test('a zero total does not divide by zero', () => {
+    // Clamped to one unit, so an empty job renders sanely rather than as NaN.
+    const bar = progressBar({ total: 0, width: 4, sink: collector(), ...off });
+    expect(bar.render()).toContain('0% 0/1');
+    expect(bar.render()).not.toContain('NaN');
+    bar.finish();
+    expect(bar.render()).toContain('100% 1/1');
+  });
+});
+
+describe('drawing stays within the terminal', () => {
+  test('a bar wider than the terminal is trimmed to fit', () => {
+    const sink = { ...collector(), isTTY: true, columns: 40 };
+    const bar = progressBar({
+      total: 10,
+      sink: sink as never,
+      enabled: true,
+      color: false,
+      text: 'a rather long label that will not fit in forty columns',
+    });
+    bar.update(5);
+    expect(bar.render().length).toBeLessThanOrEqual(40);
+  });
+
+  test('a spinner message longer than the terminal is trimmed', () => {
+    const sink = { ...collector(), isTTY: true, columns: 20 };
+    spinner('x'.repeat(100), { sink: sink as never, ...on })
+      .start()
+      .stop();
+    const longest = Math.max(
+      ...sink
+        .text()
+        .split('\r')
+        .map((l) => l.replace(/\x1b\[[0-9?]*[a-zA-Z]/g, '').length),
+    );
+    expect(longest).toBeLessThanOrEqual(20);
+  });
+});
+
+describe('redraws are throttled', () => {
+  test('a tight update loop does not write once per update', () => {
+    const sink = collector();
+    const bar = progressBar({ total: 10_000, sink, enabled: true, color: false });
+    for (let i = 0; i < 10_000; i++) {
+      bar.update(i);
+    }
+    expect(sink.text().split('\r').length - 1).toBeLessThan(50);
+  });
+
+  test('finish always lands, however recently the last redraw was', () => {
+    const sink = collector();
+    progressBar({ total: 3, sink, enabled: true, color: false }).update(1).finish();
+    expect(sink.text()).toContain('100%');
+  });
+
+  test('throttle 0 draws every update', () => {
+    const sink = collector();
+    const bar = progressBar({ total: 5, sink, enabled: true, color: false, throttle: 0 });
+    for (let i = 0; i < 5; i++) {
+      bar.update(i);
+    }
+    expect(sink.text().split('\r').length - 1).toBe(5);
+  });
+});
+
+describe('the cursor is put back', () => {
+  test('a spinner hides it while animating and restores it on succeed', () => {
+    const sink = collector();
+    const spin = spinner('working', { sink, ...on }).start();
+    expect(sink.text()).toContain('\x1b[?25l');
+    spin.succeed('done');
+    expect(sink.text()).toContain('\x1b[?25h');
+  });
+
+  test('stop restores it too', () => {
+    const sink = collector();
+    spinner('working', { sink, ...on }).start().stop();
+    expect(sink.text()).toContain('\x1b[?25h');
+  });
+
+  test('nothing is hidden when drawing is off', () => {
+    const sink = collector();
+    spinner('working', { sink, ...off }).start().stop();
+    expect(sink.text()).not.toContain('\x1b[?25l');
+  });
+});

package/src/__tests__/prompt.test.ts

@@ -0,0 +1,265 @@
+/**
+ * Tests for interactive prompts and filling missing arguments from them.
+ */
+
+import { describe, test, expect } from 'bun:test';
+import {
+  input,
+  confirm,
+  select,
+  multiselect,
+  password,
+  promptForArg,
+  promptMissing,
+  scriptedIO,
+  terminalIO,
+} from '../prompt.js';
+import { defineCommand } from '../runner.js';
+import { runCli, captureArgs } from '../testing.js';
+import type { ArgDef } from '../types.js';
+
+describe('input', () => {
+  test('returns the reply', async () => {
+    expect(await input('Name', { io: scriptedIO(['alice']) })).toBe('alice');
+  });
+
+  test('trims whitespace', async () => {
+    expect(await input('Name', { io: scriptedIO(['  alice  ']) })).toBe('alice');
+  });
+
+  test('an empty reply takes the default', async () => {
+    expect(await input('Name', { io: scriptedIO(['']), defaultValue: 'bob' })).toBe('bob');
+  });
+
+  test('the default is shown in the prompt', async () => {
+    const io = scriptedIO(['']);
+    await input('Name', { io, defaultValue: 'bob' });
+    expect(io.output).toContain('Name (bob):');
+  });
+});
+
+describe('confirm', () => {
+  test('accepts the usual affirmatives', async () => {
+    for (const answer of ['y', 'Y', 'yes', 'true', '1']) {
+      expect(await confirm('Sure', { io: scriptedIO([answer]) })).toBe(true);
+    }
+  });
+
+  test('anything else is no', async () => {
+    for (const answer of ['n', 'no', 'nope']) {
+      expect(await confirm('Sure', { io: scriptedIO([answer]) })).toBe(false);
+    }
+  });
+
+  test('an empty reply takes the default, and the hint shows which', async () => {
+    const yes = scriptedIO(['']);
+    expect(await confirm('Sure', { io: yes, defaultValue: true })).toBe(true);
+    expect(yes.output).toContain('(Y/n)');
+
+    const no = scriptedIO(['']);
+    expect(await confirm('Sure', { io: no })).toBe(false);
+    expect(no.output).toContain('(y/N)');
+  });
+});
+
+describe('select', () => {
+  const choices = ['fast', 'safe'];
+
+  test('takes a number', async () => {
+    expect(await select('Mode', choices, { io: scriptedIO(['2']) })).toBe('safe');
+  });
+
+  test('takes the value itself', async () => {
+    expect(await select('Mode', choices, { io: scriptedIO(['fast']) })).toBe('fast');
+  });
+
+  test('numbers the options and shows their help', async () => {
+    const io = scriptedIO(['1']);
+    await select('Mode', [{ name: 'fast', help: 'Skip checks' }], { io });
+    expect(io.output).toContain('1) fast  Skip checks');
+  });
+
+  test('re-asks after an answer that is not a choice', async () => {
+    const io = scriptedIO(['nonsense', '1']);
+    expect(await select('Mode', choices, { io })).toBe('fast');
+    expect(io.output).toContain('not one of the choices');
+  });
+
+  test('an out of range number is refused', async () => {
+    const io = scriptedIO(['9', '1']);
+    expect(await select('Mode', choices, { io })).toBe('fast');
+  });
+
+  test('no choices at all is a programming error', async () => {
+    await expect(select('Mode', [], { io: scriptedIO([]) })).rejects.toThrow('at least one choice');
+  });
+});
+
+describe('multiselect', () => {
+  test('takes several answers by number or name', async () => {
+    const io = scriptedIO(['1, safe']);
+    expect(await multiselect('Modes', ['fast', 'safe'], { io })).toEqual(['fast', 'safe']);
+  });
+
+  test('an empty reply picks nothing', async () => {
+    expect(await multiselect('Modes', ['a'], { io: scriptedIO(['']) })).toEqual([]);
+  });
+
+  test('one bad entry re-asks for the lot', async () => {
+    const io = scriptedIO(['1,nope', '1']);
+    expect(await multiselect('Modes', ['fast', 'safe'], { io })).toEqual(['fast']);
+    expect(io.output).toContain('not one of the choices');
+  });
+});
+
+describe('password', () => {
+  test('reads without echoing through the io', async () => {
+    expect(await password('Token', { io: scriptedIO(['hunter2']) })).toBe('hunter2');
+  });
+});
+
+describe('promptForArg', () => {
+  const ask = (def: ArgDef, answers: string[]) =>
+    promptForArg('thing', def, { io: scriptedIO(answers) });
+
+  test('a boolean asks for confirmation', async () => {
+    expect(await ask({ type: 'boolean', description: 'Enable' }, ['y'])).toBe(true);
+  });
+
+  test('possible values become a list', async () => {
+    expect(await ask({ type: 'string', valueParser: ['fast', 'safe'] }, ['2'])).toBe('safe');
+  });
+
+  test('an append arg with possible values takes several', async () => {
+    const def: ArgDef = { type: 'string', action: 'append', valueParser: ['a', 'b'] };
+    expect(await ask(def, ['1,2'])).toEqual(['a', 'b']);
+  });
+
+  test('hidden possible values are not offered', async () => {
+    const io = scriptedIO(['1']);
+    await promptForArg('thing', {
+      type: 'string',
+      valueParser: [{ name: 'shown' }, { name: 'secret', hidden: true }],
+    }, { io });
+    expect(io.output).not.toContain('secret');
+  });
+
+  test('an empty answer is refused and asked again', async () => {
+    const io = scriptedIO(['', 'value']);
+    expect(await promptForArg('thing', { type: 'string' }, { io })).toBe('value');
+    expect(io.output).toContain('a value is required');
+  });
+
+  test('a number that is not a number is refused', async () => {
+    const io = scriptedIO(['abc', '8080']);
+    expect(await promptForArg('port', { type: 'number' }, { io })).toBe('8080');
+    expect(io.output).toContain('expected a number');
+  });
+
+  test("a custom parser's complaint is shown", async () => {
+    const io = scriptedIO(['nope', 'ok']);
+    const def: ArgDef = {
+      type: 'string',
+      valueParser: (v) => {
+        if (v !== 'ok') {
+          throw new Error('must be ok');
+        }
+        return v;
+      },
+    };
+    expect(await promptForArg('thing', def, { io })).toBe('ok');
+    expect(io.output).toContain('must be ok');
+  });
+
+  test('a default is offered', async () => {
+    const io = scriptedIO(['']);
+    expect(await promptForArg('thing', { type: 'string', default: 'fallback' }, { io })).toBe(
+      'fallback',
+    );
+  });
+});
+
+describe('promptMissing', () => {
+  const main = defineCommand({
+    meta: { name: 'app' },
+    args: {
+      name: { type: 'string', required: true, description: 'Your name' },
+      port: { type: 'number', required: true, description: 'Port' },
+      given: { type: 'string' },
+    },
+    run() {},
+  });
+
+  test('asks only for what is missing', async () => {
+    const io = scriptedIO(['alice', '8080']);
+    const { args } = await captureArgs(main, ['--given', 'x'], {
+      fillMissing: promptMissing({ io }),
+    });
+    expect(args['name']).toBe('alice');
+    expect(args['port']).toBe(8080);
+    expect(args['given']).toBe('x');
+  });
+
+  test('an argument supplied on the command line is not asked about', async () => {
+    const io = scriptedIO(['8080']);
+    await captureArgs(main, ['--name', 'bob'], { fillMissing: promptMissing({ io }) });
+    expect(io.output).not.toContain('Your name');
+    expect(io.output).toContain('Port');
+  });
+
+  test('the value is coerced to the argument type', async () => {
+    const { args } = await captureArgs(main, [], {
+      fillMissing: promptMissing({ io: scriptedIO(['alice', '8080']) }),
+    });
+    expect(args['port']).toBe(8080);
+  });
+
+  test('the source is reported as prompt', async () => {
+    let source: string | undefined;
+    const probe = defineCommand({
+      meta: { name: 'app' },
+      args: { name: { type: 'string', required: true } },
+      run({ valueSources }) {
+        source = valueSources.get('name');
+      },
+    });
+    await runCli(probe, [], { fillMissing: promptMissing({ io: scriptedIO(['alice']) }) });
+    expect(source).toBe('prompt');
+  });
+
+  test('a non-interactive terminal fails as usual rather than hanging', async () => {
+    const io = { ...scriptedIO(['alice', '8080']), interactive: false };
+    const { plainStderr, exitCode } = await runCli(main, [], { fillMissing: promptMissing({ io }) });
+    expect(exitCode).toBe(2);
+    expect(plainStderr).toContain('the following required arguments were not provided');
+  });
+
+  test('force asks even when nobody appears to be there', async () => {
+    const io = { ...scriptedIO(['alice', '8080']), interactive: false };
+    const { exitCode } = await runCli(main, [], {
+      fillMissing: promptMissing({ io, force: true }),
+    });
+    expect(exitCode).toBe(0);
+  });
+
+  test('nothing missing means nothing asked', async () => {
+    const io = scriptedIO([]);
+    await runCli(main, ['--name', 'a', '--port', '1'], { fillMissing: promptMissing({ io }) });
+    expect(io.output).toBe('');
+  });
+});
+
+describe('terminalIO is shared', () => {
+  test('successive calls hand back the same interface', () => {
+    // A readline interface owns stdin: a second one finds the stream consumed,
+    // so two standalone prompts in a row would fail with "input ended".
+    expect(terminalIO()).toBe(terminalIO());
+  });
+
+  test('close releases it and the next call builds a fresh one', () => {
+    const first = terminalIO();
+    first.close();
+    expect(terminalIO()).not.toBe(first);
+    terminalIO().close();
+  });
+});