@servicetitan/startup 32.2.0 → 32.3.0

package/src/cli/commands/mfe-publish.ts

@@ -1,6 +1,6 @@
 import { getPackages, isWebComponent, logErrors, PackageType } from '../../utils';
-import { Args as CleanArgs } from './mfe-package-clean';
-import { Args as PublishArgs } from './mfe-package-publish';
+import { Args as CleanArgs, MFEPackageClean } from './mfe-package-clean';
+import { Args as PublishArgs, MFEPackagePublish } from './mfe-package-publish';
 import { Command } from './types';
 import { lernaExec } from '../utils';
 
@@ -10,11 +10,42 @@ interface Args extends PublishArgs, CleanArgs {
     scope?: string | string[];
 }
 
-export class MFEPublish implements Command {
-    constructor(private readonly args: Args) {}
+export class MFEPublish extends Command<Args> {
+    static readonly description = 'Publish or unpublish MFE packages';
+    static get options() {
+        const publishOptions = Object.entries(MFEPackagePublish.options).reduce(
+            (result, [key, value]) => {
+                result[key] = { group: 'Publish Options:', ...value };
+                return result;
+            },
+            {} as NonNullable<typeof Command.options>
+        );
+
+        const cleanOptions = Object.entries(MFEPackageClean.options).reduce(
+            (result, [key, value]) => {
+                result[Object.hasOwn(publishOptions, key) ? `${key}\u00A0` : key] = {
+                    group: 'Clean Options:',
+                    ...value,
+                };
+                return result;
+            },
+            {} as NonNullable<typeof Command.options>
+        );
 
-    description() {
-        return 'publish or unpublish MFE packages';
+        return {
+            clean: { boolean: true, description: 'Unpublish old versions' },
+            concurrency: {
+                number: true,
+                description: 'Publish/unpublish the specified number of packages concurrently',
+                defaultDescription: '1',
+            },
+            scope: {
+                array: true,
+                description: 'Publish/unpublish only the specified packages',
+            },
+            ...publishOptions,
+            ...cleanOptions,
+        };
     }
 
     @logErrors

package/src/cli/commands/prepare-package.ts

@@ -1,14 +1,12 @@
 import { logErrors } from '../../utils';
 import { copyFiles } from '../utils';
-import { Command } from './types';
+import { Command, CommandArgs } from './types';
 
-interface Args {
+interface Args extends CommandArgs {
     watch?: boolean;
 }
 
-export class PreparePackage implements Command {
-    constructor(private readonly args: Args) {}
-
+export class PreparePackage extends Command<Args> {
     @logErrors
     execute() {
         return copyFiles({ watch: this.args.watch });

package/src/cli/commands/review/review.ts

@@ -9,7 +9,7 @@ import {
     readJsonSafe,
     toArray,
 } from '../../../utils';
-import { Command } from '../types';
+import { Command, CommandArgs } from '../types';
 
 import {
     ErrorSeverity,
@@ -33,12 +33,18 @@ import { rules } from './rules';
 
 const collator = new Intl.Collator();
 
-interface Args {
+interface Args extends CommandArgs {
     fix?: boolean;
     rule?: string | string[];
 }
 
-export class Review implements Command {
+export class Review extends Command<Args> {
+    static readonly description = 'Check project for configuration errors';
+    static readonly options = {
+        fix: { boolean: true, description: 'Fix detected problems' },
+        rule: { array: true, description: 'Limit checks to specified rule(s)' },
+    };
+
     private readonly severityToLabel: Record<ErrorSeverity, string> = {
         [ErrorSeverity.warning]: chalk.yellow('warning'),
         [ErrorSeverity.error]: chalk.red('error'),
@@ -49,12 +55,6 @@ export class Review implements Command {
         error: ErrorSeverity.error,
     };
 
-    constructor(private readonly args: Args) {}
-
-    description() {
-        return 'check project for configuration errors';
-    }
-
     @logErrors
     async execute() {
         const errors = this.args.fix ? this.fixErrors() : this.findErrors();

package/src/cli/commands/run-task.ts

@@ -1,33 +1,37 @@
+/* eslint-disable @typescript-eslint/naming-convention */
 import { log, logErrors } from '../../utils';
-import { Command } from './types';
 import { SwcCompilePackage } from '../tasks/swc-compile-package';
 import { TscCompilePackage } from '../tasks/tsc-compile-package';
 import { TscCompile } from '../tasks/tsc-compile';
 import { Task } from '../tasks/task';
+import { Command, CommandArgs } from './types';
 
-interface Args {
-    [key: string]: unknown;
-    // eslint-disable-next-line @typescript-eslint/naming-convention
+interface Args extends CommandArgs {
     _: string[];
+    taskName?: string;
+    taskArgs?: string[];
 }
 
-const tasks: Record<string, new (args: Args) => Task> = {
+const tasks: Record<string, new (args: { [key: string]: unknown }) => Task> = {
     'tsc-compile-package': TscCompilePackage,
     'swc-compile-package': SwcCompilePackage,
     'tsc-compile': TscCompile,
 };
 
-export class RunTask implements Command {
-    constructor(private readonly args: Args) {}
+export class RunTask extends Command<Args> {
+    static readonly options = {
+        _: { description: '<taskName> [taskArgs...]' },
+    };
 
     @logErrors
     async execute() {
-        const taskName = this.args._[0];
+        const { _, taskName = this.args._[0], taskArgs = [], ...restOptions } = this.args;
 
         if (taskName in tasks) {
-            // eslint-disable-next-line @typescript-eslint/naming-convention
-            const trimArgs = { ...this.args, _: this.args._.slice(1) };
-            await new tasks[taskName](trimArgs).execute();
+            await new tasks[taskName]({
+                _: [..._, ...taskArgs],
+                ...restOptions,
+            }).execute();
             return;
         }
 

package/src/cli/commands/start.ts

@@ -8,9 +8,9 @@ import {
     watchStdout,
     ProcessTree,
 } from '../utils';
-import { Command } from './types';
+import { Command, CommandArgs } from './types';
 
-interface Args {
+interface Args extends CommandArgs {
     'config'?: string;
     'code-coverage'?: boolean;
     'ignore'?: string | string[];
@@ -28,14 +28,16 @@ enum StartProcesses {
     BundlePackage,
 }
 
-export class Start implements Command {
-    readonly greedy = true;
-
-    constructor(private readonly args: Args) {}
-
-    description() {
-        return 'run project in development mode';
-    }
+export class Start extends Command<Args> {
+    static readonly description = 'Run project in development mode';
+    static readonly greedy = true;
+    static readonly options = {
+        'config': { string: true, hidden: true, description: 'Use specified configuration' },
+        'code-coverage': { boolean: true, description: 'Instrument code for coverage analysis?' },
+        'ignore': { array: true, description: 'Packages to skip' },
+        'scope': { array: true, description: 'Packages to run and watch' },
+        'use-tsc': { boolean: true, description: 'Use tsc to compile packages?' },
+    };
 
     @logErrors
     async execute() {

package/src/cli/commands/styles-check.ts

@@ -2,7 +2,7 @@ import fs from 'fs';
 import { glob } from 'glob';
 import path from 'path';
 import { getFolders, isBundle, isLegacy, isStyleCheckDisabled, log, logErrors } from '../../utils';
-import { Command } from './index';
+import { Command } from './types';
 
 const patterns = [
     "@import '~@servicetitan/tokens/core/tokens.css';",
@@ -10,7 +10,7 @@ const patterns = [
     "@import '~@servicetitan/design-system/dist/system.min.css';",
 ];
 
-export class StylesCheck implements Command {
+export class StylesCheck extends Command {
     @logErrors
     async execute() {
         if (isLegacy() || !isBundle()) {

package/src/cli/commands/test/__tests__/tests.test.ts

@@ -23,7 +23,7 @@ describe(`[startup] ${Tests.name}`, () => {
     const subject = async () => new Tests(args).execute();
 
     test('command is greedy', () => {
-        expect(new Tests(args).greedy).toBe(true);
+        expect(Tests.greedy).toBe(true);
     });
 
     function itRunsJest() {

package/src/cli/commands/test/tests.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/naming-convention */
 import { Config } from '@jest/types';
 import { getConfiguration, logErrors } from '../../../utils';
 import { Command } from '../types';
@@ -5,26 +6,35 @@ import { Jest, Vitest } from './runners';
 
 type Args = Config.Argv & {
     runner?: 'jest' | 'vitest';
+    runnerArgs?: string[];
 };
 
 /**
  * This class is named "Tests" instead of "Test" because the corresponding
  * "test.ts" would be interpreted as a test file.
  */
-export class Tests implements Command {
-    readonly greedy = true;
-
-    constructor(private readonly args: Args) {}
-
-    description() {
-        return 'run tests';
-    }
+export class Tests extends Command<Args> {
+    static readonly description = 'Run tests';
+    static readonly greedy = true;
+    static readonly options = {
+        _: { description: '[runnerArgs...]' },
+        runner: {
+            choices: ['jest', 'vitest'],
+            description: 'Test runner',
+            defaultDescription: 'jest',
+        },
+    };
 
     @logErrors
     async execute() {
-        const { runner = getConfiguration().testRunner ?? 'jest', ...restArgs } = this.args;
+        const {
+            _,
+            runner = getConfiguration().testRunner ?? 'jest',
+            runnerArgs = [],
+            ...restOptions
+        } = this.args;
         if (runner === 'jest') {
-            await new Jest(restArgs).run();
+            await new Jest({ _: [..._, ...runnerArgs], ...restOptions }).run();
         } else if (runner === 'vitest') {
             await new Vitest().run();
         } else {

package/src/cli/commands/types.ts

@@ -1,7 +1,17 @@
-export interface Command {
-    greedy?: boolean;
-    execute(): Promise<void>;
-    description?(): string;
+import type { Options } from 'yargs';
+
+export interface CommandArgs {
+    [key: string]: unknown;
+}
+
+export abstract class Command<T extends CommandArgs = CommandArgs> {
+    static readonly description?: string;
+    static readonly greedy?: boolean;
+    static readonly options?: { [key: string]: Options };
+
+    constructor(protected readonly args: T) {}
+
+    abstract execute(): Promise<void>;
 }
 
 export type Newable<T> = new (...args: any[]) => T;

package/src/cli/commands/upload-sourcemaps.ts

@@ -2,9 +2,9 @@ import path from 'path';
 import { execSync } from 'child_process';
 import { getTsConfig, isWebComponent, log, logErrors, readJson } from '../../utils';
 import { isCI, TSConfig } from '../utils';
-import { Command } from './types';
+import { Command, CommandArgs } from './types';
 
-interface Args {
+interface Args extends CommandArgs {
     dry?: boolean;
     releaseVersion: string;
 }
@@ -13,12 +13,10 @@ interface PackageJson {
     name: string;
 }
 
-export class UploadSourcemaps implements Command {
+export class UploadSourcemaps extends Command<Args> {
     #outDir?: string;
     #packageJson?: PackageJson;
 
-    constructor(private readonly args: Args) {}
-
     @logErrors
     // eslint-disable-next-line @typescript-eslint/require-await
     async execute() {

package/src/cli/index.ts

@@ -1,49 +1,72 @@
+import chalk from 'chalk';
 import execa from 'execa';
 import path from 'path';
-import { argv, Arguments } from 'yargs';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
 import { CommandName, getStartupVersion, log } from '../utils';
-import { getCommand, getUserCommands } from './commands';
+import { Command, getCommand } from './commands';
 import { maybeCreateGitFolder, setNodeOptions } from './utils';
 
-const argvSync = argv as Arguments;
-const name = argvSync._[0]?.toString() as CommandName;
-if (!name) {
-    log.info(`startup cli v${getStartupVersion()}`);
-    usage();
-    process.exit(0);
-}
+Object.values(CommandName)
+    .reduce((y, name) => addCommand(name, y), yargs(hideBin(process.argv)))
+    .usage('Usage: startup <command> [options]')
+    .epilogue(
+        chalk.bold.cyan(`startup cli v${getStartupVersion()}\n`) +
+            `Run ${chalk.bold.cyan('startup <command> --help')} to see command options.\n` +
+            `For detailed documentation, see ${chalk.bold.cyan('https://docs.st.dev/docs/frontend/uikit/startup')}.\n`
+    )
+    .demandCommand(1, '')
+    .strictCommands()
+    .updateStrings({
+        'Unknown command: %s': {
+            one: chalk.bold.red('Unknown command: %s'),
+            other: chalk.bold.red('Unknown command: %s'),
+        } as any,
+    })
+    .version()
+    .wrap(Math.min(100, yargs.terminalWidth()))
+    .help()
+    .parse();
 
-const Command = getCommand(name);
-if (!Command) {
-    log.error(`Unknown command: "${name}"`);
-    usage();
-    process.exit(127);
+function addCommand(name: CommandName, y: typeof yargs) {
+    const klass = getCommand(name)! as typeof Command;
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    const { description, options: { _, ...options } = {} } = klass;
+    const nameWithArgs = name + (_?.description ? ` ${_.description}` : '');
+    const groupedOptions = Object.entries(options).reduce(
+        (result, [key, value]) => {
+            result[key] = { group: 'Command Options:', ...value };
+            return result;
+        },
+        {} as NonNullable<typeof klass.options>
+    );
+    const handler = (argv: any) => handleCommand(name, argv);
+    if (description) {
+        y.command(nameWithArgs, description, groupedOptions, handler);
+    } else {
+        y.command(nameWithArgs, false, groupedOptions, handler);
+    }
+    return y;
 }
 
-checkNodeVersion();
-maybeCreateGitFolder(Command);
+function handleCommand(name: CommandName, argv: any) {
+    const Command = getCommand(name)!;
 
-// eslint-disable-next-line @typescript-eslint/naming-convention
-const command = new Command({ ...argvSync, _: argvSync._.slice(1) });
-if (setNodeOptions(name, command)) {
-    log.debug('run', `Running ${name} in child process with amended NODE_OPTIONS`);
-    execa(process.argv[0], process.argv.slice(1), { stdio: 'inherit' }).catch(reason => {
-        process.exit(reason.exitCode);
-    });
-} else {
-    command.execute().catch(() => {
-        process.exit(1);
-    });
-}
-
-function usage() {
-    log.text('\nUsage:');
+    checkNodeVersion();
+    maybeCreateGitFolder(Command);
 
-    const commands = getUserCommands().filter(({ name }) => !!name);
-    const maxNameLength = commands.reduce((result, { name }) => Math.max(result, name.length), 0);
-    commands.forEach(({ name, description }) => {
-        log.text(`startup ${name.padEnd(maxNameLength, ' ')}  ${description}`);
-    });
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    const command = new Command({ ...argv, _: argv._.slice(1) });
+    if (setNodeOptions(name, command)) {
+        log.debug('run', `Running ${name} in child process with amended NODE_OPTIONS`);
+        execa(process.argv[0], process.argv.slice(1), { stdio: 'inherit' }).catch(reason => {
+            process.exit(reason.exitCode);
+        });
+    } else {
+        command.execute().catch(() => {
+            process.exit(1);
+        });
+    }
 }
 
 function checkNodeVersion() {

package/src/cli/tasks/swc-compile-package.ts

@@ -3,11 +3,11 @@ import debounce from 'debounce';
 import deepmerge from 'deepmerge';
 
 import { getFolders, getSwcCompilePackageConfiguration, getTsConfig, log } from '../../utils';
+import { CommandArgs } from '../commands';
 import { TSConfig } from '../utils';
 import { Task } from './task';
 
-interface Args {
-    [key: string]: unknown;
+interface Args extends CommandArgs {
     watch?: boolean;
 }
 

package/src/cli/tasks/tsc-compile-package.ts

@@ -1,7 +1,8 @@
-import { CliTask } from './cli-task';
 import { getTsConfig } from '../../utils';
-interface Args {
-    [key: string]: unknown;
+import { CommandArgs } from '../commands';
+import { CliTask } from './cli-task';
+
+interface Args extends CommandArgs {
     watch?: boolean;
 }
 

package/src/cli/tasks/tsc-compile.ts

@@ -1,8 +1,8 @@
 import { getPackages, getPackagesGraph, getTsConfig, log, Package, PackageType } from '../../utils';
+import { CommandArgs } from '../commands';
 import { CliTask } from './cli-task';
 
-interface Args {
-    [key: string]: unknown;
+interface Args extends CommandArgs {
     ignore?: string | string[];
     scope?: string | string[];
     watch?: boolean;

package/src/cli/utils/__tests__/bundle.test.ts

@@ -368,6 +368,19 @@ describe('[startup] Cli Utils', () => {
                 });
             });
         });
+
+        describe('with "useWatchConfig"', () => {
+            beforeEach(() => (options = { useWatchConfig: true }));
+
+            test('sets mode to "development"', async () => {
+                await subject();
+
+                expect(createWebpackConfig).toHaveBeenCalledWith(
+                    { configuration: { mode: 'development' } },
+                    expect.anything()
+                );
+            });
+        });
     });
 
     describe(`${bundle.name} (watch mode)`, () => {

package/src/cli/utils/__tests__/cli-npm.test.ts

@@ -7,6 +7,8 @@ import {
     npmPublish,
     npmTagVersion,
     npmUnpublish,
+    npmView,
+    npmWhoAmI,
 } from '../cli-npm';
 
 jest.mock('../cli-os', () => ({
@@ -202,4 +204,91 @@ describe('[startup] Cli Utils (Npm)', () => {
             );
         });
     });
+
+    describe(npmView.name, () => {
+        const packageInfo = { name: 'foo', version: '1.0.0', versions: [], time: {} };
+        let args: Parameters<typeof npmView>[0];
+
+        beforeEach(() => {
+            args = { packageName: '{packageName}' };
+            jest.mocked(runCommandOutput).mockReturnValue(JSON.stringify(packageInfo));
+        });
+
+        const subject = () => npmView(args);
+
+        itRunsCommandOutput(subject, 'npm view --json {packageName}', {
+            quiet: true,
+            timeout: 10000,
+        });
+
+        test('returns package info', () => {
+            expect(subject()).toEqual(packageInfo);
+        });
+
+        describe('with a registry', () => {
+            beforeEach(() => (args.registry = '{registry}'));
+
+            itRunsCommandOutput(
+                subject,
+                'npm view --json --registry={registry} {packageName}',
+                expect.anything()
+            );
+        });
+
+        describe('when command fails', () => {
+            const error = new Error('Oops!');
+
+            beforeEach(() => {
+                jest.mocked(runCommandOutput).mockImplementation(() => {
+                    throw error;
+                });
+            });
+
+            test('returns undefined', () => {
+                expect(subject()).toBeUndefined();
+            });
+        });
+    });
+
+    describe(npmWhoAmI.name, () => {
+        const username = 'Foo\n';
+        let args: Parameters<typeof npmWhoAmI>[0];
+
+        beforeEach(() => {
+            args = undefined;
+            jest.mocked(runCommandOutput).mockReturnValue(username);
+        });
+
+        const subject = () => npmWhoAmI(args);
+
+        itRunsCommandOutput(subject, 'npm whoami', {
+            quiet: true,
+            stdio: ['pipe', 'pipe', 'ignore'],
+            timeout: 10000,
+        });
+
+        test('returns trimmed username ', () => {
+            expect(subject()).toEqual(username.trim());
+        });
+
+        describe('with registry', () => {
+            beforeEach(() => (args = { registry: '{registry}' }));
+
+            itRunsCommandOutput(subject, 'npm whoami --registry={registry}', expect.anything());
+        });
+
+        describe('when command fails', () => {
+            const error = new Error('Oops');
+
+            beforeEach(() => {
+                jest.mocked(runCommandOutput).mockImplementation(() => {
+                    throw error;
+                });
+            });
+
+            test('ignores error and returns undefined', () => {
+                expect(subject()).toBeUndefined();
+            });
+        });
+    });
 });

package/src/cli/utils/__tests__/is-tty.test.ts

@@ -0,0 +1,17 @@
+import { isTTY } from '../is-tty';
+
+describe(`[startup] Utils ${isTTY.name}`, () => {
+    const originalIsTTY = process.stdin.isTTY;
+
+    afterAll(() => process.stdin.isTTY === originalIsTTY);
+
+    const subject = () => isTTY();
+
+    describe.each([true, false])('when process.stdin.isTTY is %s', value => {
+        beforeEach(() => (process.stdin.isTTY = value));
+
+        test(`returns ${value}`, () => {
+            expect(subject()).toBe(value);
+        });
+    });
+});

package/src/cli/utils/__tests__/maybe-create-git-folder.test.ts

@@ -2,6 +2,7 @@ import { fs, vol } from 'memfs';
 
 import { maybeCreateGitFolder } from '../maybe-create-git-folder';
 import { Init } from '../../commands/init';
+import { Install } from '../../commands/install';
 import { Start } from '../../commands/start';
 
 jest.mock('fs', () => fs);
@@ -28,28 +29,20 @@ describe(`[startup] Utils`, () => {
             });
         }
 
-        describe('when running on Windows', () => {
-            beforeEach(() => {
-                Object.defineProperty(process, 'platform', { value: 'win32' });
-            });
-
-            test('creates .git folder', () => {
-                subject();
+        test('creates .git folder', () => {
+            subject();
 
-                expect(mkdirSpy).toHaveBeenCalledWith('.git', { recursive: true });
-            });
+            expect(mkdirSpy).toHaveBeenCalledWith('.git', { recursive: true });
+        });
 
-            describe('when command is Init', () => {
-                beforeEach(() => (command = Init));
+        describe('when command is Init', () => {
+            beforeEach(() => (command = Init));
 
-                itDoesNotCreateGitFolder();
-            });
+            itDoesNotCreateGitFolder();
         });
 
-        describe('when not running on Windows', () => {
-            beforeEach(() => {
-                Object.defineProperty(process, 'platform', { value: 'linux' });
-            });
+        describe('when command is Install', () => {
+            beforeEach(() => (command = Install));
 
             itDoesNotCreateGitFolder();
         });