@yahoo/uds 2.0.0 → 2.1.0

package/cli/README.md

@@ -3,6 +3,11 @@ import { Box, VStack } from '@yahoo/uds';
 import { RequiredChip } from '~/components/RequiredChip';
 import { DocImage } from '~/components/DocImage';
 import { PACKAGE_MANAGERS, CommandSnippet } from '~/components/CommandSnippet';
+import { toPageTitle } from '~/utils/toPageTitle';
+
+export const metadata = {
+title: toPageTitle({ title: 'CLI', category: 'Tools' }),
+};
 
 # Universal CLI
 
@@ -18,6 +23,17 @@ The Universal CLI is available as command, `uds`. The tool was created with [Blu
 
 1. To use the CLI, first [install](/docs/getting-started/quick-start#installation) the `@yahoo/uds` package as a dependency in your package.json, which has the UDS CLI as a binary.
 
+2. Log in to the CLI
+
+<VStack spacingBottom="2">
+  <DocTabs
+    items={PACKAGE_MANAGERS.map((packageManager) => ({
+      label: packageManager,
+      content: <CommandSnippet name={packageManager} command="bun uds login" />,
+    }))}
+  />
+</VStack>
+
 ## Commands
 
 > **Note**: If you are _not_ running the CLI from a package.json script you will need to call your package manager execute command before the binary in order to run it directly. i.e. `npx uds purge`
@@ -128,6 +144,24 @@ Any file added to commands/codemod will be available in prompt land.
 uds codemod
 ```
 
+### Login
+
+The `uds login` command is used to authenticate the user to the CLI. We use
+Google's OAuth2 flow, which is the same login flow used by the [Configurator](/docs/getting-started/using-configurator) and the documentation site. Logging in to the CLI helps us identify and track CLI usage and metrics.
+
+### Circumventing Login
+
+There may be situations (such as CI runs) where you can't authenticate your personal account with the CLI. For this case, providing the `CI=true` and `UDS_TEAM_SLUG` env variables is required when using the CLI in a CI environment:
+
+```env
+CI=true
+UDS_TEAM_SLUG=<your-team-slug> uds <command>
+```
+
+Your team slug can be found in your team's Configurator URL path:
+
+<DocImage light={{ src: '/images/team-slug-screenshot.png' }} />
+
 ### Expo (WIP)
 
 The `uds expo` command is for building and launching React Native apps using Expo.
@@ -153,6 +187,22 @@ Commands are organized in a tree structure in `uds/cli/commands`. The root comma
 
 Adding nested commands, i.e. `uds expo dev` does work correctly when UDS is consumed from npm. As a workaround, please see code for expo/expo.ts for re-routing sub-commands from the root command file. To verify your CLI command works correctly you should run `npm pack` within the packages/uds directory. Once you have your generated tarball you should copy that tarball to a test application such as https://github.com/yahoo-uds/uds-nextjs-demo, then add `"@yahoo/uds": "file:./tarball-generated-from-npm-pack.tgz` to it's dependencies and run an install. Now you should be able to run `bun uds [your command name]` to test your functionality.
 
+### Testing the login flow
+
+To test the login flow, the CLI starts a web server and opens browser window to
+a login page in Configurator. In prod, it opens https://config.uds.build/login.
+In local dev, http://localhost:4001/login is opened.
+
+In the root of the UDS monorepo, run the following commands:
+
+```
+# Start configurator app web server:
+turbo --filter uds-configurator dev
+
+# Run the CLI login command:
+bun run --cwd packages/uds uds login
+```
+
 ### API Reference
 
 Bluebun comes with a number of built-in utilities that are exported from the main `bluebun` package. See [reference guide](https://github.com/jamonholmgren/bluebun/blob/main/docs/reference.md) for more.

package/cli/cli.ts

@@ -2,12 +2,14 @@
 // Start bluebun to run the correct CLI command
 import { parseArgs } from 'node:util';
 
-import { run } from 'bluebun';
+import { print, red, run } from 'bluebun';
 
-function main() {
+import { getAuthenticatedUser } from './utils/auth';
+
+async function main() {
   // We need to pass the path from Node to the Bun binaries
   // because there's an issue where the Bun binaries struggle to resolve
-  const { values } = parseArgs({
+  const { values, positionals } = parseArgs({
     args: Bun.argv,
     options: {
       commandsPath: {
@@ -18,9 +20,24 @@ function main() {
     allowPositionals: true,
   });
 
+  const cliPath = values.commandsPath!.toString();
+  const isLoginCmd = positionals.includes('login');
+
+  if (!isLoginCmd) {
+    const user = await getAuthenticatedUser(cliPath);
+    if (!user) {
+      print(
+        red(
+          '🚨 Sign-in required. Please run `uds login` and use a @yahooinc.com email during sign-in.',
+        ),
+      );
+      return;
+    }
+  }
+
   run({
     name: 'uds',
-    cliPath: values.commandsPath!.toString(),
+    cliPath,
   });
 }
 

package/cli/commands/codemod/codemod.ts

@@ -1,6 +1,7 @@
 import { type Props } from 'bluebun';
 import prompts from 'prompts';
 
+import { trackEvent } from '../../utils/analytics';
 import { getCommandHelp, getSubCommandsChoices } from '../../utils/getCommandHelp';
 import { getDirChoices } from '../../utils/getDirChoices';
 
@@ -13,6 +14,11 @@ export default {
     const isRootCommand = Boolean(!props?.first);
     const dirChoices = getDirChoices();
 
+    const runCodeMod = async (codemod: string, selectedDirs: string[]) => {
+      const mod = (await import(`./${codemod}`)).default;
+      return mod.run({ ...props, selectedDirs });
+    };
+
     if (isRootCommand) {
       // Prompt the user to setup the codemod runner
       const { selectedDirs, selectedCodemods, didConfirm } = await prompts([
@@ -49,10 +55,9 @@ export default {
 
       // Run each codemod and provide the selectedDirs
       return Promise.all(
-        selectedCodemods.map(async (selectedCodemod: string[]) => {
-          return await import(`./${selectedCodemod}`).then((codemod) =>
-            codemod.default.run({ ...props, selectedDirs }),
-          );
+        selectedCodemods.map(async (codemod: string) => {
+          await runCodeMod(codemod, selectedDirs);
+          return trackEvent('codemod', { codemod });
         }),
       );
     } else if (subCommandIsValid) {
@@ -71,11 +76,9 @@ export default {
         process.exit(1);
       }
 
-      // Run the codemod
-      return (await import(`./${props.first}`)).default.run({
-        ...props,
-        selectedDirs,
-      });
+      const codemod = props.first!;
+      await runCodeMod(codemod, selectedDirs);
+      return trackEvent('codemod', { codemod });
     } else {
       // Throw the help message
       await getCommandHelp({

package/cli/commands/codemod/sizingProps.ts

@@ -6,7 +6,7 @@ import { sizingPropToClassMap } from '../../codemods/utils/sizingPropToClassMap'
 export default {
   name: 'sizingProps',
   description: `Convert sizing props to classNames`,
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+
   run: async (props: Props & { selectedDirs?: string[] }) => {
     spinStart('Running codemod...');
 

package/cli/commands/login.ts

@@ -0,0 +1,30 @@
+import { magenta, print, red } from 'bluebun';
+
+import { trackEvent } from '../utils/analytics';
+import { login } from '../utils/auth';
+
+export default {
+  name: 'login',
+  description: '👤 Log in to UDS CLI',
+  alias: ['auth'],
+  run: async () => {
+    try {
+      const user = await login();
+      if (user) {
+        print(magenta(`🔒 Logged in as ${user.email}`));
+        return await trackEvent('login');
+      }
+    } catch (error) {
+      if (error instanceof Error) {
+        print(red(error.message));
+      } else {
+        print(
+          red(
+            `❌ An error occurred while logging in. Please ask in the #uds-ask channel for support.`,
+          ),
+        );
+        process.exitCode = 1;
+      }
+    }
+  },
+};

package/cli/commands/logout.ts

@@ -0,0 +1,27 @@
+import { magenta, print, red } from 'bluebun';
+
+import { trackEvent } from '../utils/analytics';
+import { logout } from '../utils/auth';
+
+export default {
+  name: 'logout',
+  description: '👤 Sign out of UDS CLI',
+  run: async () => {
+    try {
+      // Track logout event before logout is run. Otherwise, there's no user object to track.
+      await trackEvent('logout');
+      await logout();
+      print(magenta('👋 You have been logged out.'));
+    } catch (error) {
+      if (error instanceof Error) {
+        print(red(error.message));
+      } else {
+        print(
+          red(
+            `❌ An error occurred while logging out. Please ask in the #uds-ask channel for support.`,
+          ),
+        );
+      }
+    }
+  },
+};

package/cli/commands/purge.ts

@@ -1,5 +1,6 @@
 import { Props, spinStart, spinStop } from 'bluebun';
 
+import { trackEvent } from '../utils/analytics';
 import { purge, PurgeOptions } from '../utils/purgeCSS';
 
 interface PurgeProps extends Props {
@@ -9,12 +10,13 @@ interface PurgeProps extends Props {
 export default {
   name: 'purge',
   description: `Purge unused CSS`,
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+
   run: async (props: PurgeProps) => {
     spinStart('Purging css started...');
     try {
       await purge(props.options);
       spinStop('✅', 'Purging css done!');
+      return await trackEvent('purge');
     } catch (error) {
       if (error instanceof Error) {
         spinStop('❌', error.message);

package/cli/commands/sync.ts

@@ -1,5 +1,6 @@
 import { magenta, print, Props } from 'bluebun';
 
+import { trackEvent } from '../utils/analytics';
 import { setupConfigWorker } from '../utils/setupConfigWorker';
 import { SyncOptions } from '../utils/types';
 
@@ -31,6 +32,7 @@ export default {
           }
         },
       });
+      return await trackEvent('sync', { id });
     } catch {
       console.error(
         '❌ An error occurred while syncing. Please reach out to #uds-ask channel for support.',

package/cli/commands/uds.ts

@@ -1,5 +1,7 @@
 import { print, type Props, red } from 'bluebun';
 
+import { trackEvent } from '../utils/analytics';
+import { getAuthenticatedUser } from '../utils/auth';
 import { getCommandHelp } from '../utils/getCommandHelp';
 
 export default {
@@ -8,7 +10,10 @@ export default {
   run: async (props: Props) => {
     if (props.first) {
       print(red(`Unknown command: ${props.first}`));
+      await trackEvent('unknown_cmd', { cmd: props.first });
     }
-    await getCommandHelp(props);
+    const user = await getAuthenticatedUser();
+    const notes = user ? `🔒 Logged in as ${user.email}` : undefined;
+    await getCommandHelp({ ...props, notes });
   },
 };

package/cli/commands/version.ts

@@ -1,11 +1,13 @@
 import { print } from 'bluebun';
 
 import packageJson from '../../package.json';
+import { trackEvent } from '../utils/analytics';
 
 export default {
   name: 'version',
   description: `${packageJson.version}`,
   run: async () => {
     print(packageJson.version);
+    await trackEvent('version', { version: packageJson.version });
   },
 };

package/cli/compile.ts

@@ -11,25 +11,24 @@ const __dirname = path.dirname(__filename);
 const libPath = __dirname;
 const entry = path.join(libPath, './cli.ts');
 
-const main = async () => {
+async function main() {
   // Compile the UDS CLI for all the supported platforms
   await Promise.all(
-    SUPPORTED_BUN_PLATFORMS.map(async (supportedPlatform) => {
-      console.log(`Building UDS CLI for ${supportedPlatform}`);
-      await $`bun build --compile --minify --sourcemap --target=bun-${supportedPlatform} ${entry} --outfile ${path.join(libPath, './bin', `./uds-${supportedPlatform}`)} `;
+    SUPPORTED_BUN_PLATFORMS.map((platform) => {
+      console.log(`Building UDS CLI for ${platform}`);
+      return $`bun build --compile --minify --sourcemap --target=bun-${platform} ${entry} --outfile ${path.join(libPath, './bin', `./uds-${platform}`)}`.quiet();
     }),
   );
 
   // Compile the script that will auto-detect the platform and architecture
-  const shellOutput = await $`bun build ${path.join(libPath, './exec.ts')} --target node`;
+  const shellOutput = await $`bun build ${path.join(libPath, './exec.ts')} --target node`.text();
 
   // Add shebang at the top of the file and write to disk
   await Bun.write(
     path.join(libPath, './uds-cli'),
     `#!/usr/bin/env node \n
-// Note: This file is generated, do not edit directly! Edit exec.ts instead. \n` +
-      shellOutput.text(),
+// Note: This file is generated, do not edit directly! Edit exec.ts instead. \n` + shellOutput,
   );
-};
+}
 
-await main();
+main();

package/cli/consts.ts

@@ -1,3 +1,7 @@
 // Supported target platforms by Bun
 // https://bun.sh/docs/bundler/executables#cross-compile-to-other-platforms
-export const SUPPORTED_BUN_PLATFORMS = ['linux-x64-baseline', 'darwin-arm64-baseline'];
+export const SUPPORTED_BUN_PLATFORMS = [
+  'linux-x64-baseline',
+  'linux-arm64',
+  'darwin-arm64-baseline',
+];

package/cli/env.d.ts

@@ -14,6 +14,11 @@ declare module 'bun' {
     EXPO_USE_METRO_WORKSPACE_ROOT?: string;
     EXPO_BUNDLE_APP?: string;
     ESLINT_USE_FLAT_CONFIG?: string;
+    /** UDS purge command - which color and scale modes to keep */
     ENABLED_SCALE_AND_COLOR_MODES?: string;
+    /** UDS config id */
+    UDS_ID?: string;
+    /** UDS sync command - filename to write the config output */
+    UDS_OUT_FILE?: string;
   }
 }

package/cli/exec.ts

@@ -28,7 +28,7 @@ const detectPlatform = () => {
     });
   } else {
     throw new Error(
-      'Unsupported platform 😢, pleaes reach out to the UDS team for support #uds-ask.',
+      'Unsupported platform 😢, please reach out to the UDS team for support #uds-ask.',
     );
   }
 };

package/cli/preload.ts

@@ -44,3 +44,20 @@ mock.module('@yahoo/uds/tailwind/purger', () => ({
     Button: '',
   },
 }));
+
+mock.module('googleapis', () => ({
+  google: {
+    auth: {
+      OAuth2: mock(() => {}).mockImplementation(() => ({
+        getToken: () => Promise.resolve({ tokens: 'test' }),
+        setCredentials: mock(() => {}),
+        generateAuthUrl: mock(() => 'https://accounts.google.com/o/oauth2/v2/auth'),
+      })),
+    },
+    oauth2: () => ({
+      userinfo: {
+        get: () => Promise.resolve({ data: { email: 'foo@yahooinc.com' } }),
+      },
+    }),
+  },
+}));

package/cli/tsconfig.json

@@ -18,14 +18,14 @@
     "strict": true,
     "types": ["bun-types"],
     "target": "esnext",
-    "lib": ["esnext"],
+    "lib": ["ESNext"],
     "module": "esnext",
     "moduleResolution": "bundler",
     "paths": {
       "@yahoo/uds/scripts/*": ["../scripts/*"],
       "@yahoo/uds/*": ["../src/*"],
       "@yahoo/uds/tailwind/tsMorph": ["../scripts/utils/tsMorph.ts"],
-      "root/*": ["../../*"],
-    },
-  },
+      "root/*": ["../../*"]
+    }
+  }
 }

package/cli/uds-cli

@@ -7,7 +7,11 @@ import path from "path";
 import { fileURLToPath } from "url";
 
 // cli/consts.ts
-var SUPPORTED_BUN_PLATFORMS = ["linux-x64-baseline", "darwin-arm64-baseline"];
+var SUPPORTED_BUN_PLATFORMS = [
+  "linux-x64-baseline",
+  "linux-arm64",
+  "darwin-arm64-baseline"
+];
 
 // cli/exec.ts
 var detectPlatform = () => {
@@ -23,7 +27,7 @@ var detectPlatform = () => {
       stdio: "inherit"
     });
   } else {
-    throw new Error("Unsupported platform \uD83D\uDE22, pleaes reach out to the UDS team for support #uds-ask.");
+    throw new Error("Unsupported platform \uD83D\uDE22, please reach out to the UDS team for support #uds-ask.");
   }
 };
 detectPlatform();

package/cli/utils/analytics.ts

@@ -0,0 +1,26 @@
+import {
+  type EventName,
+  GA_MEASUREMENT_IDS,
+  GA_MEASUREMENT_SECRETS,
+  track,
+} from '@yahoo/uds/analytics/server';
+
+import { getAuthenticatedUser } from './auth';
+
+export async function setup() {
+  const user = await getAuthenticatedUser();
+  if (user) {
+    await track.init({
+      appName: 'cli',
+      apiSecret: GA_MEASUREMENT_SECRETS.cli,
+      measurementId: GA_MEASUREMENT_IDS.cli,
+      // @ts-expect-error type is fine
+      user,
+    });
+  }
+}
+
+export async function trackEvent(...args: Parameters<typeof track.event<EventName['cli']>>) {
+  await setup();
+  await track.event(...args);
+}