@servicetitan/startup 38.1.0 → 38.3.0

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

@@ -1,6 +1,14 @@
+import { Attributes, telemetry } from '../../../telemetry';
 import { exitWhenParentExits } from '../../../utils';
 import { Command } from '../command';
 
+jest.mock('../../../telemetry', () => ({
+    telemetry: {
+        info: jest.fn(),
+        error: jest.fn(),
+        flush: jest.fn(() => Promise.resolve()),
+    },
+}));
 jest.mock('../../../utils', () => ({
     exitWhenParentExits: jest.fn(),
 }));
@@ -9,10 +17,21 @@ class MockCommand extends Command {
     execute() {
         return Promise.resolve();
     }
+
+    recordStart(command: string, attributes?: Attributes): void {
+        return super.recordStart(command, attributes);
+    }
+
+    recordEnd(error?: unknown): Promise<void> {
+        return super.recordEnd(error);
+    }
 }
 
 describe(`[startup] ${Command.name} entity`, () => {
     const name: any = 'mock-command';
+    const commandName = 'build';
+    const attributes: Attributes = { bundler: 'vite' };
+
     let args: any;
 
     beforeEach(() => {
@@ -39,4 +58,97 @@ describe(`[startup] ${Command.name} entity`, () => {
             });
         });
     });
+
+    describe('recordStart', () => {
+        let command: MockCommand;
+
+        beforeEach(() => (command = new MockCommand(args)));
+
+        const subject = () => command.recordStart(commandName, attributes);
+
+        test('emits a command.started event with the attributes', () => {
+            subject();
+
+            expect(telemetry.info).toHaveBeenCalledWith(
+                'command.started',
+                expect.objectContaining({
+                    ...attributes,
+                    command: commandName,
+                    runId: expect.any(String),
+                })
+            );
+        });
+
+        describe('when a run is already active', () => {
+            beforeEach(() => command.recordStart(commandName, attributes));
+
+            test('does not start a second run', () => {
+                subject();
+
+                expect(telemetry.info).toHaveBeenCalledTimes(1);
+            });
+        });
+    });
+
+    describe('recordEnd', () => {
+        let error: unknown;
+        let command: MockCommand;
+
+        beforeEach(() => {
+            error = undefined;
+            command = new MockCommand(args);
+        });
+
+        const subject = () => command.recordEnd(error);
+
+        test('does not emit anything', async () => {
+            await subject();
+
+            expect(telemetry.info).not.toHaveBeenCalled();
+            expect(telemetry.error).not.toHaveBeenCalled();
+        });
+
+        describe('when called after recordStart', () => {
+            beforeEach(() => command.recordStart(commandName, attributes));
+
+            test('emits a command.finished event with a duration', async () => {
+                await subject();
+
+                expect(telemetry.info).toHaveBeenCalledWith(
+                    'command.finished',
+                    expect.objectContaining({
+                        ...attributes,
+                        command: commandName,
+                        runId: expect.any(String),
+                        duration: expect.any(Number),
+                    })
+                );
+            });
+
+            test('flushes pending telemetry', async () => {
+                await subject();
+
+                expect(telemetry.flush).toHaveBeenCalled();
+            });
+
+            describe('with an error', () => {
+                beforeEach(() => (error = new Error('boom')));
+
+                test('emits a command.finished error event', async () => {
+                    await subject();
+
+                    expect(telemetry.error).toHaveBeenCalledWith(
+                        'command.finished',
+                        error,
+                        expect.objectContaining({
+                            ...attributes,
+                            command: commandName,
+                            runId: expect.any(String),
+                            duration: expect.any(Number),
+                        })
+                    );
+                });
+            });
+        });
+    });
 });

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

@@ -40,7 +40,7 @@ describe(`[startup] ${Init.name}`, () => {
             force: true,
         });
         expect(fs.rmSync).toHaveBeenCalledWith(path.join(cwd, '.github', 'CODEOWNERS'));
-        expect(fs.rmSync).toHaveBeenCalledWith(path.join(cwd, 'package-lock.json'));
+        expect(fs.rmSync).not.toHaveBeenCalledWith(path.join(cwd, 'package-lock.json'));
     });
 
     describe('when cloning fails', () => {

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

@@ -1,83 +1,16 @@
-import { execSync } from 'child_process';
-import { getStartupVersion } from '../../../core';
-import { log } from '../../../utils';
 import { Install } from '../install';
 import { entry } from '../registry/install';
 
-jest.mock('child_process', () => ({ execSync: jest.fn() }));
-jest.mock('../../../core', () => ({
-    ...jest.requireActual('../../../core'),
-    getStartupVersion: jest.fn(),
-}));
-jest.mock('../../../utils', () => ({
-    ...jest.requireActual('../../../utils'),
-    log: { debug: jest.fn(), info: jest.fn() }, // suppress log output
-}));
-
 describe(`${Install.name}`, () => {
-    const startupVersion = '1.2.3';
-    let args: ConstructorParameters<typeof Install>[0];
-
-    beforeEach(() => {
-        args = {};
-        jest.clearAllMocks();
-        jest.mocked(getStartupVersion).mockReturnValue(startupVersion);
-    });
-
-    const subject = async () => new Install(args).execute();
+    const subject = async () => new Install({}).execute();
 
     test('allows running from global location', () => {
         expect(entry.allowRunFromGlobal).toBe(true);
     });
 
-    test('runs install', async () => {
-        await subject();
-
-        expect(execSync).toHaveBeenCalledWith(`npx --yes @servicetitan/install`, {
-            stdio: 'inherit',
-        });
-    });
-
-    const keys = ['fix', 'quiet', 'token'] satisfies (keyof typeof args)[];
-    describe.each(keys)('with --%s', option => {
-        beforeEach(() => (args[option] = true));
-
-        test(`runs install with --${option}`, async () => {
-            await subject();
-
-            expect(execSync).toHaveBeenCalledWith(
-                expect.stringContaining(`--${option}`),
-                expect.anything()
-            );
-        });
-    });
-
-    describe('with --no-token', () => {
-        beforeEach(() => (args.token = false));
-
-        test('runs install with --no-token', async () => {
-            await subject();
-
-            expect(execSync).toHaveBeenCalledWith(
-                expect.stringContaining('--no-token'),
-                expect.anything()
-            );
-        });
-    });
-
-    test('logs progress', async () => {
-        await subject();
-
-        expect(log.info).toHaveBeenCalledWith(`startup cli v${startupVersion}`);
-    });
-
-    describe('with --quiet', () => {
-        beforeEach(() => (args = { quiet: true }));
-
-        test('does not log progress', async () => {
-            await subject();
-
-            expect(log.info).not.toHaveBeenCalled();
-        });
+    test('throws guidance pointing to @servicetitan/install', async () => {
+        await expect(subject()).rejects.toThrow(
+            'The `startup install` command has been removed. Run `npx --yes @servicetitan/install` directly instead.'
+        );
     });
 });

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

@@ -1,6 +1,8 @@
 import { createPackage } from '../../../__mocks__';
-import { Package, PackageType, getConfiguration, getPackages, log } from '../../../utils';
-import { compile, lernaExec, typeCheck, watchStdout } from '../../utils';
+import { Attributes } from '../../../telemetry';
+import { getConfiguration, getPackages, log, Package, PackageType } from '../../../utils';
+import { compile, lernaExec, ProcessTree, typeCheck, watchStdout } from '../../utils';
+import { Command } from '../command';
 import { entry } from '../registry/start';
 import { Start } from '../start';
 
@@ -31,12 +33,20 @@ jest.mock('../../utils', () => ({
 }));
 
 describe(`[startup] ${Start.name}`, () => {
+    const commandProto = Command.prototype as unknown as {
+        recordStart: (command: string, attributes?: Attributes) => void;
+        recordEnd: (error?: unknown) => Promise<void>;
+    };
+
     let args: ConstructorParameters<typeof Start>[0];
     let packages: Package[];
+    let recordStart: jest.SpyInstance;
+    let recordEnd: jest.SpyInstance;
 
     beforeEach(() => {
         args = {};
         packages = [];
+        jest.restoreAllMocks();
         jest.clearAllMocks();
         jest.mocked(getConfiguration).mockReturnValue({});
         jest.mocked(getPackages).mockImplementation(() => packages);
@@ -44,6 +54,8 @@ describe(`[startup] ${Start.name}`, () => {
             handler(packages.length);
             return jest.fn();
         });
+        recordStart = jest.spyOn(commandProto, 'recordStart').mockImplementation(() => {});
+        recordEnd = jest.spyOn(commandProto, 'recordEnd').mockResolvedValue(undefined);
     });
 
     const subject = () => new Start(args).execute();
@@ -113,6 +125,35 @@ describe(`[startup] ${Start.name}`, () => {
         expect(process.env.STARTUP_PARENT_PID).toBe(String(process.pid));
     });
 
+    describe('telemetry', () => {
+        beforeEach(() => packages.push(createPackage({ type: PackageType.TSC })));
+
+        test('records the command start', async () => {
+            await subject();
+
+            expect(recordStart).toHaveBeenCalledWith('start', { bundler: expect.any(String) });
+        });
+
+        describe('when start fails', () => {
+            const error = new Error('watch failed');
+
+            beforeEach(() => {
+                jest.spyOn(log, 'error').mockImplementation(jest.fn());
+                jest.spyOn(ProcessTree.prototype, 'run').mockRejectedValue(error);
+            });
+
+            test('records the failure', async () => {
+                await subject().catch(() => {});
+
+                expect(recordEnd).toHaveBeenCalledWith(error);
+            });
+
+            test('propagates the error', async () => {
+                await expect(subject()).rejects.toBe(error);
+            });
+        });
+    });
+
     describe('with TSC package', () => {
         beforeEach(() => packages.push(createPackage({ type: PackageType.TSC })));
 

package/src/cli/commands/build.ts

@@ -30,6 +30,8 @@ export class Build extends Command<typeof entry> {
             return;
         }
 
+        this.recordStart('build', { bundler: resolveBundler(this.args) });
+
         if (this.args.cdnPath) {
             process.env.CLIENT_CDN_PATH = this.args.cdnPath;
         }
@@ -115,6 +117,12 @@ export class Build extends Command<typeof entry> {
             { dependsOn: [BuildProcesses.BundleExposedDependencies] }
         );
 
-        await processTree.run();
+        try {
+            await processTree.run();
+        } catch (error) {
+            await this.recordEnd(error);
+            throw error;
+        }
+        this.recordEnd();
     }
 }

package/src/cli/commands/command.ts

@@ -1,7 +1,20 @@
+import { randomUUID } from 'crypto';
+import { Attributes, telemetry } from '../../telemetry';
 import { CommandName, exitWhenParentExits } from '../../utils';
 import { CommandEntry, InferArgs } from './types';
 
+const NS_PER_MS = 1_000_000;
+
+interface CommandRun {
+    command: string;
+    runId: string;
+    startedAt: number;
+    attributes?: Attributes;
+}
+
 export abstract class Command<T extends CommandEntry = CommandEntry, U = unknown> {
+    private commandRun?: CommandRun;
+
     constructor(protected readonly args: InferArgs<NonNullable<T['options']>, U>) {}
 
     watchForParentExit(name: CommandName): void {
@@ -10,5 +23,42 @@ export abstract class Command<T extends CommandEntry = CommandEntry, U = unknown
         }
     }
 
+    protected recordStart(command: string, attributes?: Attributes): void {
+        if (this.commandRun) {
+            return;
+        }
+        this.commandRun = {
+            command,
+            runId: randomUUID(),
+            startedAt: globalThis.performance.now(),
+            attributes,
+        };
+        telemetry.info('command.started', {
+            ...attributes,
+            command,
+            runId: this.commandRun.runId,
+        });
+    }
+
+    protected recordEnd(error?: unknown): Promise<void> {
+        const run = this.commandRun;
+        if (!run) {
+            return Promise.resolve();
+        }
+        this.commandRun = undefined;
+        const attributes = {
+            ...run.attributes,
+            command: run.command,
+            runId: run.runId,
+            duration: Math.round((globalThis.performance.now() - run.startedAt) * NS_PER_MS),
+        };
+        if (error !== undefined) {
+            telemetry.error('command.finished', error, attributes);
+        } else {
+            telemetry.info('command.finished', attributes);
+        }
+        return telemetry.flush();
+    }
+
     abstract execute(): Promise<void>;
 }

package/src/cli/commands/init.ts

@@ -39,7 +39,6 @@ export class Init extends Command<typeof entry> {
 
         fs.rmSync(path.join(destination, '.git'), { recursive: true, force: true });
         fs.rmSync(path.join(destination, '.github', 'CODEOWNERS'));
-        fs.rmSync(path.join(destination, 'package-lock.json'));
         return true;
     }
 }

package/src/cli/commands/install.ts

@@ -1,29 +1,13 @@
-import { execSync } from 'child_process';
-import { getStartupVersion } from '../../core';
-import { log, logErrors } from '../../utils';
+import { logErrors } from '../../utils';
 import type { entry } from './registry/install';
 import { Command } from './types';
 
 export class Install extends Command<typeof entry> {
     @logErrors
+    // eslint-disable-next-line @typescript-eslint/require-await
     async execute() {
-        if (!this.args.quiet) {
-            log.info(`startup cli v${getStartupVersion()}`);
-        }
-
-        const options = [
-            this.args.fix ? '--fix' : '',
-            this.args.quiet ? '--quiet' : '',
-            this.args.token === true ? '--token' : '',
-            this.args.token === false ? '--no-token' : '',
-        ].filter(option => !!option);
-
-        const command = `npx --yes @servicetitan/install ${options.join(' ')}`.trim();
-
-        log.debug('install', command);
-
-        execSync(command, { stdio: 'inherit' });
-
-        return Promise.resolve(); // stops "async method has no 'await' expression" lint error
+        throw new Error(
+            'The `startup install` command has been removed. Run `npx --yes @servicetitan/install` directly instead.'
+        );
     }
 }

package/src/cli/commands/registry/install.ts

@@ -3,10 +3,5 @@ import { defineEntry } from './define-entry';
 
 export const entry = defineEntry({
     allowRunFromGlobal: true,
-    description: 'Install project dependencies',
-    options: {
-        fix: { boolean: true, description: 'Update and dedupe package-lock.json', hidden: true },
-        quiet: { boolean: true, description: 'Suppress output', hidden: true },
-        token: { boolean: true, description: 'Configure npm token' },
-    },
+    description: 'Removed. Run `npx --yes @servicetitan/install` directly instead.',
 } satisfies CommandEntry);

package/src/cli/commands/start.ts

@@ -42,6 +42,8 @@ export class Start extends Command<typeof entry> {
             return;
         }
 
+        this.recordStart('start', { bundler: resolveBundler(this.args) });
+
         const scope = packages.map(({ name }) => name);
         const bundleScope = packages
             .filter(({ type }) => type === PackageType.Bundle)
@@ -160,6 +162,11 @@ export class Start extends Command<typeof entry> {
             { dependsOn: [StartProcesses.BundleExposedDependencies] }
         );
 
-        await processTree.run();
+        try {
+            await processTree.run();
+        } catch (error) {
+            await this.recordEnd(error);
+            throw error;
+        }
     }
 }

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

@@ -1,7 +1,7 @@
-import { gitGetBranch, gitGetCommitHash } from '../cli-git';
-import { runCommandOutput } from '../cli-os';
+import { gitGetBranch, gitGetCommitHash, gitGetContext } from '../cli-git';
+import { runCommandOutput, runCommandOutputAsync } from '../cli-os';
 
-jest.mock('../cli-os', () => ({ runCommandOutput: jest.fn() }));
+jest.mock('../cli-os', () => ({ runCommandOutput: jest.fn(), runCommandOutputAsync: jest.fn() }));
 
 describe('[startup] Cli Utils (Git)', () => {
     beforeEach(() => {
@@ -26,4 +26,55 @@ describe('[startup] Cli Utils (Git)', () => {
     describe(gitGetCommitHash.name, () => {
         itRunsCommand(gitGetCommitHash, 'git rev-parse --short HEAD');
     });
+
+    describe(gitGetContext.name, () => {
+        const root = '/repos/monolith';
+        const context = {
+            repo: 'monolith',
+            branch: 'main',
+            userEmail: 'dev@st.com',
+            userName: 'dev',
+        };
+
+        let output: Record<string, string | undefined>;
+
+        beforeEach(() => {
+            output = {
+                'rev-parse': `${context.branch}\n${root}`,
+                'user.email': context.userEmail,
+                'user.name': context.userName,
+            };
+            jest.mocked(runCommandOutputAsync).mockImplementation(command => {
+                const key = Object.keys(output).find(entry => String(command).includes(entry));
+                return Promise.resolve(key ? output[key] : undefined);
+            });
+        });
+
+        const subject = () => gitGetContext();
+
+        test('collects the repo, branch, and user', async () => {
+            expect(await subject()).toEqual(context);
+        });
+
+        describe('when one command fails', () => {
+            beforeEach(() => (output['user.email'] = undefined));
+
+            test('leaves only that field undefined', async () => {
+                expect(await subject()).toEqual({ ...context, userEmail: undefined });
+            });
+        });
+
+        describe('when every command fails', () => {
+            beforeEach(() => (output = {}));
+
+            test('leaves the fields undefined', async () => {
+                expect(await subject()).toEqual({
+                    repo: undefined,
+                    branch: undefined,
+                    userEmail: undefined,
+                    userName: undefined,
+                });
+            });
+        });
+    });
 });

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

@@ -1,8 +1,9 @@
-import { execFileSync, execSync, spawn } from 'child_process';
+import { exec, execFileSync, execSync, spawn } from 'child_process';
 import { log } from '../../../utils';
-import { killProcessTree, runCommand, runCommandOutput } from '../cli-os';
+import { killProcessTree, runCommand, runCommandOutput, runCommandOutputAsync } from '../cli-os';
 
 jest.mock('child_process', () => ({
+    exec: jest.fn(),
     execFileSync: jest.fn(),
     execSync: jest.fn(),
     spawn: jest.fn(),
@@ -143,6 +144,101 @@ describe('[startup] Cli Utils (OS)', () => {
         });
     });
 
+    describe(`${runCommandOutputAsync.name}`, () => {
+        // promisify(exec) resolves with { stdout, stderr }; the mock supplies that shape.
+        const mockExec = (
+            impl: (callback: (error: Error | null, result?: { stdout: string }) => void) => void
+        ) =>
+            jest
+                .mocked(exec)
+                .mockImplementation(((
+                    _command: string,
+                    _options: unknown,
+                    callback: (error: Error | null, result?: { stdout: string }) => void
+                ) => impl(callback)) as unknown as typeof exec);
+
+        let command: string;
+        let options: NonNullable<Parameters<typeof runCommandOutputAsync>[1]>;
+
+        beforeEach(() => {
+            jest.clearAllMocks();
+            command = 'foo';
+            options = {};
+            mockExec(callback => callback(null, { stdout: 'result\n' }));
+        });
+
+        const subject = () => runCommandOutputAsync(command, options);
+
+        test('resolves with the trimmed result', async () => {
+            await expect(subject()).resolves.toBe('result');
+        });
+
+        test('runs the command', async () => {
+            await subject();
+
+            expect(exec).toHaveBeenCalledWith(command, options, expect.any(Function));
+        });
+
+        describe('when the output is empty', () => {
+            beforeEach(() => mockExec(callback => callback(null, { stdout: '   ' })));
+
+            test('resolves with undefined', async () => {
+                await expect(subject()).resolves.toBeUndefined();
+            });
+        });
+
+        describe('with options', () => {
+            beforeEach(() => (options.timeout = 10000));
+
+            test('passes them through', async () => {
+                await subject();
+
+                expect(exec).toHaveBeenCalledWith(command, options, expect.any(Function));
+            });
+        });
+
+        test('logs the command', async () => {
+            const logInfoSpy = jest.spyOn(log, 'info');
+            await subject();
+
+            expect(logInfoSpy).toHaveBeenCalledWith(`Running: ${command}`);
+        });
+
+        test('logs the result', async () => {
+            const logInfoSpy = jest.spyOn(log, 'info');
+            await subject();
+
+            expect(logInfoSpy).toHaveBeenCalledWith('command finished', 'result');
+        });
+
+        describe('with quiet', () => {
+            beforeEach(() => (options.quiet = true));
+
+            test('suppresses output', async () => {
+                const logInfoSpy = jest.spyOn(log, 'info');
+                await subject();
+
+                expect(logInfoSpy).not.toHaveBeenCalled();
+            });
+        });
+
+        describe('when the command fails', () => {
+            beforeEach(() => mockExec(callback => callback(new Error('boom'))));
+
+            test('rejects', async () => {
+                await expect(subject()).rejects.toThrow('boom');
+            });
+
+            describe('with ignoreErrors', () => {
+                beforeEach(() => (options.ignoreErrors = true));
+
+                test('resolves with undefined', async () => {
+                    await expect(subject()).resolves.toBeUndefined();
+                });
+            });
+        });
+    });
+
     describe(`${killProcessTree.name}`, () => {
         const pid = 1234;
         const originalPlatform = process.platform;