[ts-command-line] Add defineCommandLineRemainder() feature

build-tests/ts-command-line-test/.vscode/launch.json

@@ -0,0 +1,15 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Widget CLI",
+      "program": "${workspaceFolder}/lib/start.js",
+      "args": [ "run", "1", "2", "3" ]
+    }
+  ]
+}

build-tests/ts-command-line-test/build.js

@@ -0,0 +1,20 @@
+const fsx = require('fs-extra');
+const child_process = require('child_process');
+const path = require('path');
+const process = require('process');
+
+function executeCommand(command) {
+  console.log('---> ' + command);
+  child_process.execSync(command, { stdio: 'inherit' });
+}
+
+// Clean the old build outputs
+console.log(`==> Starting build.js for ${path.basename(process.cwd())}`);
+fsx.emptyDirSync('dist');
+fsx.emptyDirSync('lib');
+fsx.emptyDirSync('temp');
+
+// Run the TypeScript compiler
+executeCommand('node node_modules/typescript/lib/tsc');
+
+console.log(`==> Finished build.js for ${path.basename(process.cwd())}`);

build-tests/ts-command-line-test/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "ts-command-line-test",
+  "description": "Building this project is a regression test for ts-command-line",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "build": "node build.js",
+    "start": "node ./lib/start.js"
+  },
+  "devDependencies": {
+    "@rushstack/ts-command-line": "4.3.14",
+    "@types/node": "10.17.13",
+    "fs-extra": "~7.0.1",
+    "typescript": "~3.7.2"
+  }
+}

build-tests/ts-command-line-test/src/BusinessLogic.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+export class BusinessLogic {
+  public static async doTheWork(force: boolean): Promise<void> {
+    console.log(`Business logic did the work. (force=${force}) `);
+  }
+
+  public static configureLogger(verbose: boolean): void {
+    console.log(`Business logic configured the logger. (verbose=${verbose}) `);
+  }
+}

build-tests/ts-command-line-test/src/PushAction.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { CommandLineFlagParameter, CommandLineAction, CommandLineChoiceParameter } from '@rushstack/ts-command-line';
+import { BusinessLogic } from './BusinessLogic';
+
+export class PushAction extends CommandLineAction {
+  private _force: CommandLineFlagParameter;
+  private _protocol: CommandLineChoiceParameter;
+
+  public constructor() {
+    super({
+      actionName: 'push',
+      summary: 'Pushes a widget to the service',
+      documentation: 'Your long description goes here.'
+    });
+  }
+
+  protected onExecute(): Promise<void> { // abstract
+    return BusinessLogic.doTheWork(this._force.value);
+  }
+
+  protected onDefineParameters(): void { // abstract
+    this._force = this.defineFlagParameter({
+      parameterLongName: '--force',
+      parameterShortName: '-f',
+      description: 'Push and overwrite any existing state'
+    });
+
+    this._protocol = this.defineChoiceParameter({
+      parameterLongName: '--protocol',
+      description: 'Specify the protocol to use',
+      alternatives: ['ftp', 'webdav', 'scp'],
+      environmentVariable: 'WIDGET_PROTOCOL',
+      defaultValue: 'scp'
+    });
+  }
+}

build-tests/ts-command-line-test/src/RunAction.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { CommandLineAction, CommandLineStringParameter } from '@rushstack/ts-command-line';
+
+
+export class RunAction extends CommandLineAction {
+  private _title: CommandLineStringParameter;
+
+  public constructor() {
+    super({
+      actionName: 'run',
+      summary: 'Runs the rest of the command line as a shell command',
+      documentation: 'Your long description goes here.'
+    });
+  }
+
+  protected onExecute(): Promise<void> { // abstract
+    console.log(`Title: ${this._title.value || '(none)'}`);
+    console.log('Remainder: ' + JSON.stringify(this.remainder!.values));
+
+    return Promise.resolve();
+  }
+
+  protected onDefineParameters(): void { // abstract
+    this._title = this.defineStringParameter({
+      parameterLongName: '--title',
+      argumentName: 'TITLE',
+      description: 'An optional title to show'
+    });
+
+    this.defineCommandLineRemainder({
+      description: 'The remaining arguments will be blah.'
+    });
+  }
+}

build-tests/ts-command-line-test/src/WidgetCommandLine.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { CommandLineParser, CommandLineFlagParameter } from '@rushstack/ts-command-line';
+import { PushAction } from './PushAction';
+import { RunAction } from './RunAction';
+import { BusinessLogic } from './BusinessLogic';
+
+export class WidgetCommandLine extends CommandLineParser {
+  private _verbose: CommandLineFlagParameter;
+
+  public constructor() {
+    super({
+      toolFilename: 'widget',
+      toolDescription: 'The widget tool is really great.'
+    });
+
+    this.addAction(new PushAction());
+    this.addAction(new RunAction());
+  }
+
+  protected onDefineParameters(): void { // abstract
+    this._verbose = this.defineFlagParameter({
+      parameterLongName: '--verbose',
+      parameterShortName: '-v',
+      description: 'Show extra logging detail'
+    });
+  }
+
+  protected onExecute(): Promise<void> { // override
+    BusinessLogic.configureLogger(this._verbose.value);
+    return super.onExecute();
+  }
+}

build-tests/ts-command-line-test/src/start.ts

@@ -0,0 +1,7 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { WidgetCommandLine } from './WidgetCommandLine';
+
+const commandLine: WidgetCommandLine = new WidgetCommandLine();
+commandLine.execute();

build-tests/ts-command-line-test/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "es6",
+    "forceConsistentCasingInFileNames": true,
+    "module": "commonjs",
+    "declaration": true,
+    "sourceMap": true,
+    "experimentalDecorators": true,
+    "strictNullChecks": true,
+    "types": [
+      "node"
+    ],
+    "lib": [
+      "es5",
+      "scripthost",
+      "es2015.collection",
+      "es2015.promise",
+      "es2015.iterable",
+      "dom"
+    ],
+    "outDir": "lib"
+  },
+  "include": [
+    "src/**/*.ts",
+    "typings/tsd.d.ts"
+  ]
+}

build-tests/ts-command-line-test/widget.cmd

@@ -0,0 +1,2 @@
+@echo off
+node .\lib\start.js %*

build-tests/ts-command-line-test/widget.sh

@@ -0,0 +1,2 @@
+#!/bin/sh
+exec node ./lib/start.js "$@"

common/changes/@rushstack/ts-command-line/octogonz-tsc-improvements_2020-05-14-09-44.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/ts-command-line",
+      "comment": "Add a new feature defineCommandLineRemainder() which allows additional unvalidated CLI arguments, e.g. to pass along to another tool",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/ts-command-line",
+  "email": "[email protected]"
+}

common/changes/@rushstack/ts-command-line/octogonz-tsc-improvements_2020-05-14-09-45.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/ts-command-line",
+      "comment": "Fix a bug with environmentVariable mapping for CommandLineFlagParameter",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@rushstack/ts-command-line",
+  "email": "[email protected]"
+}

common/changes/@rushstack/ts-command-line/octogonz-tsc-improvements_2020-05-14-09-46.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/ts-command-line",
+      "comment": "Add the ability for an environment variable to specify multiple values for CommandLineStringListParameter, encoded as a JSON array",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/ts-command-line",
+  "email": "[email protected]"
+}

common/changes/@rushstack/ts-command-line/octogonz-tsc-improvements_2020-05-14-09-47.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/ts-command-line",
+      "comment": "Use API Extractor to trim internal APIs from the .d.ts rollup",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@rushstack/ts-command-line",
+  "email": "[email protected]"
+}

common/changes/@rushstack/ts-command-line/octogonz-tsc-improvements_2020-05-14-09-48.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/ts-command-line",
+      "comment": "Fix some bugs that prevented a CommandLineParser from being defined without any actions",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/ts-command-line",
+  "email": "[email protected]"
+}

common/changes/@rushstack/ts-command-line/octogonz-tsc-improvements_2020-05-14-09-49.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/ts-command-line",
+      "comment": "Improve the README.md and API documentation",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@rushstack/ts-command-line",
+  "email": "[email protected]"
+}

common/config/rush/nonbrowser-approved-packages.json

@@ -2,6 +2,10 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/approved-packages.schema.json",
   "packages": [
+    {
+      "name": "@microsoft/ts-command-line",
+      "allowedCategories": [ "tests" ]
+    },
     {
       "name": "@jest/core",
       "allowedCategories": [ "libraries" ]
@@ -176,7 +180,7 @@
     },
     {
       "name": "@rushstack/ts-command-line",
-      "allowedCategories": [ "libraries" ]
+      "allowedCategories": [ "libraries", "tests" ]
     },
     {
       "name": "@rushstack/typings-generator",