feat: enable debug mode

.github/README.md

@@ -212,13 +212,22 @@ Also, make sure that your `cypress.config.js|mjs|cjs|ts` is formatted accordingl
 
 ## Troubleshooting
 
-Enable the debug mode and run the command:
+Enable the debug mode by adding `--cloud-debug true | all | cypress | currents | commit-info` flag
+
+- `true | all` enable debug mode for all the tools
+- `cypress` activate debug mode for cypress only
+- `currents` activate the debug mode for currents only
+- `commit-info` activate the debug mode for git commit info only
 
 ```sh
-DEBUG=currents:* npx cypress-cloud run ...
+# show all the debug information
+npx cypress-cloud run ... --cloud-debug
+
+# show only currents related debug information
+npx cypress-cloud run ... --cloud-debug currents,commit-info
 ```
 
-Capture all the logs in a plain text file and submit an issue.
+Capture all the logs as a plain text file and share it with the support team for further troubleshooting.
 
 ## Testing
 

examples/webapp/currents.config.js

@@ -7,7 +7,7 @@ module.exports = {
   },
   projectId: !!(process.env.GITHUB_ACTION || process.env.CIRCLE_BRANCH)
     ? "Ij0RfK"
-    : "1OPP8c",
+    : "Ij0RfK",
   // cloudServiceUrl: "http://localhost:1234",
-userAgent: "custom"
+  userAgent: "custom",
 };

packages/cypress-cloud/bin/lib/cli.ts

@@ -1,5 +1,6 @@
 import { CurrentsRunParameters, TestingType } from "cypress-cloud/types";
 import Debug from "debug";
+import { activateDebug } from "../../lib/debug";
 import { sanitizeAndConvertNestedArgs } from "./parser";
 import { program } from "./program";
 
@@ -9,15 +10,17 @@ export function parseCLIOptions(
   _program: typeof program = program,
   ...args: Parameters<typeof program.parse>
 ) {
-  _program.parse(...args);
-  debug("parsed CLI flags %o", _program.opts());
+  const opts = _program.parse(...args).opts();
 
-  const { e2e, component } = _program.opts();
+  activateDebug(opts.cloudDebug);
+  debug("parsed CLI flags %o", opts);
+
+  const { e2e, component } = opts;
   if (e2e && component) {
     _program.error("Cannot use both e2e and component options");
   }
 
-  return getRunParametersFromCLI(_program.opts());
+  return getRunParametersFromCLI(opts);
 }
 
 /**

packages/cypress-cloud/bin/lib/program.ts

@@ -1,6 +1,7 @@
 // https://github.com/currents-dev/cypress-cloud/issues/71
 // keep the local copy to prevent from importing
 // commander.js from the global node_modules
+import { DebugMode } from "../../types";
 import { Command, Option } from "./@commander-js/extra-typings";
 
 export const createProgram = (command: Command = new Command()) =>
@@ -103,6 +104,18 @@ export const createProgram = (command: Command = new Command()) =>
         "--cloud-config-file <path>",
         "Specify the config file for cypress-cloud, defaults to 'currents.config.js' and will be searched in the project root, unless an aboslue path is provided"
       ).default(undefined)
+    )
+    .addOption(
+      new Option(
+        `--cloud-debug [true | string]`,
+        `Enable debug mode for cypress-cloud, this will print out logs for troubleshooting. Values: [true | ${Object.values(
+          DebugMode
+        ).join(
+          " | "
+        )}]. Use comma to separate multiple values, e.g. --cloud-debug commit-info,currents`
+      )
+        .argParser(parseCommaSeparatedList)
+        .default(undefined)
     );
 
 export const program = createProgram();

packages/cypress-cloud/lib/config/params.ts

@@ -166,6 +166,7 @@ export function getCypressRunAPIParams(
   return {
     ..._.pickBy(
       _.omit(params, [
+        "cloudDebug",
         "cloudConfigFile",
         "autoCancelAfterFailures",
         "cloudServiceUrl",

packages/cypress-cloud/lib/debug/index.ts

@@ -0,0 +1,44 @@
+import debug from "debug";
+import { match, P } from "ts-pattern";
+import { CurrentsRunParameters, DebugMode } from "../../types";
+
+enum DebugTokens {
+  Currents = "currents:*",
+  Cypress = "cypress:*",
+  CommitInfo = "commit-info",
+}
+export function activateDebug(mode: CurrentsRunParameters["cloudDebug"]) {
+  match(mode)
+    .with(P.instanceOf(Array), (i) => i.forEach(setDebugMode))
+    .with(true, () => setDebugMode(DebugMode.All))
+    .with(
+      P.union(
+        DebugMode.All,
+        DebugMode.Currents,
+        DebugMode.Cypress,
+        DebugMode.CommitInfo
+      ),
+      (i) => setDebugMode(i)
+    )
+    .otherwise(() => setDebugMode(DebugMode.None));
+}
+
+function setDebugMode(mode: string) {
+  if (mode === DebugMode.None) {
+    return;
+  }
+
+  const tokens = new Set(process.env.DEBUG ? process.env.DEBUG.split(",") : []);
+  match(mode)
+    .with(DebugMode.All, () => {
+      tokens.add(DebugTokens.CommitInfo);
+      tokens.add(DebugTokens.Currents);
+      tokens.add(DebugTokens.Cypress);
+    })
+    .with(DebugMode.Currents, () => tokens.add(DebugTokens.Currents))
+    .with(DebugMode.Cypress, () => tokens.add(DebugTokens.Cypress))
+    .with(DebugMode.CommitInfo, () => tokens.add(DebugTokens.CommitInfo))
+    .otherwise(() => {});
+
+  debug.enable(Array.from(tokens).join(","));
+}

packages/cypress-cloud/lib/run.ts

@@ -12,6 +12,7 @@ import {
   validateParams,
 } from "./config";
 import { runBareCypress } from "./cypress";
+import { activateDebug } from "./debug";
 import { getGitInfo } from "./git";
 import { setAPIBaseUrl, setRunId } from "./httpClient";
 import { bold, divider, info, spacer, title } from "./log";
@@ -35,6 +36,7 @@ import { startWSS } from "./ws";
 const debug = Debug("currents:run");
 
 export async function run(params: CurrentsRunParameters = {}) {
+  activateDebug(params.cloudDebug);
   debug("run params %o", params);
   params = preprocessParams(params);
   debug("params after preprocess %o", params);

packages/cypress-cloud/types.ts

@@ -91,6 +91,14 @@ export type ScreenshotArtifact = CypressCommandLine.ScreenshotInformation & {
   screenshotId: string;
 };
 
+export enum DebugMode {
+  None = "none",
+  All = "all",
+  Currents = "currents",
+  Cypress = "cypress",
+  CommitInfo = "commit-info",
+}
+
 // Explicitly filter cypress record-related flags - prevent triggering recording mode to avoid confusion
 export type StrippedCypressModuleAPIOptions = Omit<
   Partial<CypressCommandLine.CypressRunOptions>,
@@ -163,6 +171,11 @@ export type CurrentsRunParameters = StrippedCypressModuleAPIOptions & {
    * Configuration file name or absolute path. Default value is 'currents.config.js', if specified, must be a string. The file will be resolved relative to the project root, unless it's an absolute path.
    */
   cloudConfigFile?: string;
+
+  /**
+   * Enable debug mode for cypress-cloud, this will print out logs for troubleshooting.
+   */
+  cloudDebug?: DebugMode | true | string | string[];
 };
 
 // User-facing `run` interface