@clerk/dev-cli 0.0.1-canary.v5356e51

package/.eslintrc.cjs

@@ -0,0 +1,8 @@
+module.exports = {
+  root: true,
+  extends: ['@clerk/custom/node', '@clerk/custom/typescript', '@clerk/custom/jest'],
+  rules: {
+    // allowList all environment variables since we don't use Turborepo for clerk-dev anyway.
+    'turbo/no-undeclared-env-vars': ['error', { allowList: ['.*'] }],
+  },
+};

package/README.md

@@ -0,0 +1,88 @@
+# `clerk-dev` CLI
+
+The `clerk-dev` CLI is a tool designed to simplify the process of iterating on packages within the `clerk/javascript` repository within sample applications, such as customer reproductions. It allows for the installation of the monorepo versions of packages, and supports features such as hot module reloading for increased development velocity.
+
+## Installation
+
+```sh
+npm install --global @clerk/dev-cli
+```
+
+If you haven't already, install `turbo` globally.
+
+```sh
+npm install --global turbo
+```
+
+## First time setup
+
+After installing `@clerk/dev` globally, you'll need to initialise a configuration file and tell the CLI where to find your local copy of the `clerk/javascript` repository.
+
+1.  Initialise the configuration file which will be located at `~/.config/clerk/dev.json`:
+
+        ```shell
+        clerk-dev init
+        ```
+
+2.  Navigate to your local clone of `clerk/javascript` and run `set-root`:
+
+        ```shell
+        clerk-dev set-root
+        ```
+
+You're all set now to run the day-to-day commands 🎉
+
+## Adding instances & changing the configuration
+
+During the first time setup a `~/.config/clerk/dev.json` file was created. Its object contains a `activeInstance` and `instances` key. You can add additional instances by adding a new key to the `instances` object.
+
+You can use the `set-instance` command to switch between `activeInstance` afterwards:
+
+```shell
+clerk-dev set-instance yourName
+```
+
+## Per-Project Setup
+
+In each project you'd like to use with the monorepo versions of Clerk packages, `clerk-dev` can perform one-time framework setup such as installing the monorepo versions of packages and configuring the framework to use your Clerk keys.
+
+To perform framework setup, run:
+
+```sh
+clerk-dev setup
+```
+
+If you aren't working on `@clerk/clerk-js`, and do not want to customize the `clerkJSUrl`, pass `--no-js`.
+
+```sh
+clerk-dev setup --no-js
+```
+
+If you want to skip the installation of monorepo versions of packages, pass `--skip-install`.
+
+```sh
+clerk-dev setup --skip-install
+```
+
+## Running
+
+Once your project has been configured to use the monorepo versions of your dependencies, you can start the watchers for each dependency by running:
+
+```sh
+clerk-dev watch
+```
+
+This will run the `build` task for any `@clerk/*` packages in the `package.json` of the current working directory, including any of their dependencies.
+
+> [!NOTE]
+> On macOS, this command will automatically spawn a new Terminal.app window running the dev task for `clerk-js`. On other operating systems, you will need to run the following command in a new terminal:
+>
+> ```sh
+> clerk-dev watch --js
+> ```
+
+If you do not want to spawn the watcher for `@clerk/clerk-js`, you can instead pass `--no-js`.
+
+```sh
+clerk-dev watch --no-js
+```

package/bin/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import cli from '../src/cli.js';
+
+cli();

package/jsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": false,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "importHelpers": true,
+    "isolatedModules": true,
+    "moduleResolution": "NodeNext",
+    "module": "NodeNext",
+    "noImplicitReturns": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "resolveJsonModule": true,
+    "sourceMap": false,
+    "strict": true,
+    "target": "ES2020",
+    "outDir": "dist",
+    "types": ["jest"],
+    "checkJs": true
+  },
+  "exclude": ["node_modules"],
+  "include": ["src/"]
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@clerk/dev-cli",
+  "version": "0.0.1-canary.v5356e51",
+  "license": "MIT",
+  "type": "module",
+  "author": "Clerk",
+  "homepage": "https://clerk.com/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clerk/javascript.git",
+    "directory": "packages/dev-cli"
+  },
+  "main": "bin/cli.js",
+  "bin": {
+    "clerk-dev": "bin/cli.js"
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "scripts": {
+    "lint": "eslint src/"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "dotenv": "^16.4.5",
+    "globby": "^14.0.2",
+    "jscodeshift": "^0.16.1"
+  },
+  "devDependencies": {
+    "@clerk/eslint-config-custom": "*",
+    "@types/node": "^20.14.8",
+    "typescript": "*"
+  }
+}

package/schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$ref": "#/definitions/Configuration",
+  "definitions": {
+    "Configuration": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "$schema": { "type": "string" },
+        "root": {
+          "anyOf": [{ "type": "string" }, { "type": "null" }]
+        },
+        "activeInstance": {
+          "type": "string"
+        },
+        "instances": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/InstanceConfiguration"
+          }
+        }
+      },
+      "required": ["root", "activeInstance", "instances"],
+      "title": "Configuration"
+    },
+    "InstanceConfiguration": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "secretKey": {
+          "type": "string"
+        },
+        "publishableKey": {
+          "type": "string"
+        },
+        "fapiUrl": {
+          "type": "string"
+        },
+        "bapiUrl": {
+          "type": "string"
+        }
+      },
+      "required": ["secretKey", "publishableKey", "fapiUrl", "bapiUrl"],
+      "title": "InstanceConfiguration"
+    }
+  }
+}

package/src/cli.js

@@ -0,0 +1,69 @@
+import { Command } from 'commander';
+
+import { config } from './commands/config.js';
+import { init } from './commands/init.js';
+import { setInstance } from './commands/set-instance.js';
+import { setRoot } from './commands/set-root.js';
+import { setup } from './commands/setup.js';
+import { watch } from './commands/watch.js';
+
+export default function cli() {
+  const program = new Command();
+
+  program.name('clerk-dev').description('CLI to make developing Clerk packages easier').version('0.0.0');
+
+  program
+    .command('init')
+    .description('Perform initial one-time machine setup')
+    .action(async () => {
+      await init();
+    });
+
+  program
+    .command('config')
+    .description('Open the clerk-dev config file in EDITOR or VISUAL')
+    .action(async () => {
+      await config();
+    });
+
+  program
+    .command('set-root')
+    .description(
+      'Set the location of your checkout of the clerk/javascript repository to the current working directory',
+    )
+    .action(async () => {
+      await setRoot();
+    });
+
+  program
+    .command('set-instance')
+    .description('Set the active instance to the provided instance name')
+    .argument('<name>', 'name of instance listed in dev.json')
+    .action(async instance => {
+      await setInstance({ instance });
+    });
+
+  program
+    .command('setup')
+    .description(
+      'Install the monorepo versions of Clerk packages listed in the package.json file and perform framework configuration for the current working directory',
+    )
+    .option('--no-js', 'do not customize the clerkJSUrl')
+    .option('--skip-install', 'only perform framework configuration; do not install monorepo versions of packages')
+    .action(async ({ js, skipInstall }) => {
+      await setup({ js, skipInstall });
+    });
+
+  program
+    .command('watch')
+    .description(
+      'Start the dev tasks for all Clerk packages listed in the package.json file in the current working directory, including clerk-js (unless --no-js is specified)',
+    )
+    .option('--js', 'only start the watcher for clerk-js')
+    .option('--no-js', 'do not spawn the clerk-js watcher (macOS only)')
+    .action(async ({ js }) => {
+      await watch({ js });
+    });
+
+  program.parseAsync();
+}

package/src/codemods/index.js

@@ -0,0 +1,19 @@
+import { join } from 'node:path';
+
+import { run } from 'jscodeshift/src/Runner.js';
+
+/**
+ *
+ * @param {string} transform
+ * @param {string[]} paths
+ */
+export async function applyCodemod(transform, paths) {
+  const pathToTransform = join(import.meta.dirname, 'transforms', transform);
+  return await run(pathToTransform, paths, {
+    ignorePattern: ['**/node_modules/**', '**/dist/**'],
+    extensions: 'tsx,ts,jsx,js',
+    parser: 'tsx',
+    silent: true,
+    runInBand: true,
+  });
+}

package/src/codemods/transforms/add-clerkjsurl-to-provider.cjs

@@ -0,0 +1,32 @@
+const CLERK_JS_URL_PROP = 'clerkJSUrl';
+const CLERK_JS_URL = 'http://localhost:4000/npm/clerk.browser.js';
+
+/**
+ *
+ * @param {import('jscodeshift').FileInfo} file
+ * @param {import('jscodeshift').API} api
+ */
+module.exports = function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+
+  const clerkProvider = root.findJSXElements('ClerkProvider');
+
+  if (clerkProvider.size() > 0) {
+    clerkProvider.forEach(clerkProviderElement => {
+      const attrs = clerkProviderElement.get('attributes');
+      const hasClerkJSUrlProp = attrs.value.some(n => n.name.name === CLERK_JS_URL_PROP);
+      if (hasClerkJSUrlProp) {
+        for (const attr of attrs.value) {
+          if (attr.name.name === CLERK_JS_URL_PROP) {
+            attr.value = j.literal(CLERK_JS_URL);
+          }
+        }
+      } else {
+        attrs.push(j.jsxAttribute(j.jsxIdentifier(CLERK_JS_URL_PROP), j.literal(CLERK_JS_URL)));
+      }
+    });
+  }
+
+  return root.toSource();
+};

package/src/commands/auth.js

@@ -0,0 +1,4 @@
+/**
+ * TODO - authenticate to Clerk to fetch keys and persist them to the config file
+ */
+export async function auth() {}

package/src/commands/config.js

@@ -0,0 +1,26 @@
+import { spawn } from 'node:child_process';
+
+import { CONFIG_FILE } from '../utils/getConfiguration.js';
+
+/**
+ * Opens the clerk-dev config file in VISUAL or EDITOR.
+ */
+export async function config() {
+  if (process.env.VISUAL) {
+    spawn(process.env.VISUAL, [CONFIG_FILE], {
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+      },
+    });
+  } else if (process.env.EDITOR) {
+    spawn(process.env.EDITOR, [CONFIG_FILE], {
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+      },
+    });
+  } else {
+    console.error(`Unable to open clerk-dev config file. Make sure the EDITOR or VISUAL environment variable is set.`);
+  }
+}

package/src/commands/init.js

@@ -0,0 +1,50 @@
+import { spawn } from 'node:child_process';
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { CONFIG_FILE } from '../utils/getConfiguration.js';
+import { getCLIRoot } from '../utils/getMonorepoRoot.js';
+
+/**
+ * Performs one-time machine-level configuration tasks such as creating a blank config file.
+ */
+export async function init() {
+  const cliRoot = getCLIRoot();
+
+  /** @type import('../utils/getConfiguration.js').Configuration */
+  const configuration = {
+    $schema: join(cliRoot, 'packages', 'dev', 'schema.json'),
+    root: null,
+    activeInstance: 'default',
+    instances: {
+      default: {
+        secretKey: 'sk_REPLACE_WITH_SECRET_KEY',
+        publishableKey: 'pk_REPLACE_WITH_PUBLISHABLE_KEY',
+        fapiUrl: 'REPLACE_WITH_FAPI_URL',
+        bapiUrl: 'https://api.clerk.com',
+      },
+    },
+  };
+
+  await writeFile(CONFIG_FILE, JSON.stringify(configuration, null, 2), 'utf-8');
+
+  if (process.env.VISUAL) {
+    spawn(process.env.VISUAL, [CONFIG_FILE], {
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+      },
+    });
+    console.log(`Configuration file written to ${CONFIG_FILE}.`);
+  } else if (process.env.EDITOR) {
+    spawn(process.env.EDITOR, [CONFIG_FILE], {
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+      },
+    });
+    console.log(`Configuration file written to ${CONFIG_FILE}.`);
+  } else {
+    console.log(`Configuration file written to ${CONFIG_FILE}. Replace with your values.`);
+  }
+}

package/src/commands/set-instance.js

@@ -0,0 +1,20 @@
+import { writeFile } from 'node:fs/promises';
+
+import { CONFIG_FILE, getConfiguration } from '../utils/getConfiguration.js';
+
+/**
+ * Sets the active instance to the provided instance name.
+ * @param {object} args
+ * @param {string} args.instance
+ */
+export async function setInstance({ instance }) {
+  const config = await getConfiguration();
+
+  if (!(instance in config.instances)) {
+    throw new Error(`Instance "${instance}" not found in dev.json.`);
+  }
+
+  const newConfig = { ...config, activeInstance: instance };
+  await writeFile(CONFIG_FILE, JSON.stringify(newConfig, null, 2), 'utf-8');
+  console.log(`clerk-dev activeInstance set to ${instance}.`);
+}

package/src/commands/set-root.js

@@ -0,0 +1,21 @@
+import { readFile, writeFile } from 'node:fs/promises';
+
+import { CONFIG_FILE, getConfiguration } from '../utils/getConfiguration.js';
+
+/**
+ * Sets the location of the clerk/javascript monorepo to the machine-level config file.
+ */
+export async function setRoot() {
+  const config = await getConfiguration();
+  const cwd = process.cwd();
+
+  const packageJSON = await readFile('package.json', 'utf-8');
+  const pkg = JSON.parse(packageJSON);
+  if (pkg.name !== '@clerk/javascript') {
+    throw new Error('clerk-dev set-root needs to be run within a local checkout of the clerk/javascript repository.');
+  }
+
+  const newConfig = { ...config, root: process.cwd() };
+  await writeFile(CONFIG_FILE, JSON.stringify(newConfig, null, 2), 'utf-8');
+  console.log(`clerk-dev root set to ${cwd}.`);
+}

package/src/commands/setup.js

@@ -0,0 +1,202 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { parse } from 'dotenv';
+
+import { applyCodemod } from '../codemods/index.js';
+import { getClerkPackages } from '../utils/getClerkPackages.js';
+import { getConfiguration } from '../utils/getConfiguration.js';
+import { getDependencies } from '../utils/getDependencies.js';
+
+/**
+ * Returns `true` if the cwd contains a file named `filename`, otherwise returns `false`.
+ * @param {string} filename
+ * @returns {boolean}
+ */
+function hasFile(filename) {
+  return existsSync(join(process.cwd(), filename));
+}
+
+/**
+ * Returns `true` if `packages` contains a `dependency` key, otherwise `false`.
+ * @param {Record<string, string> | undefined} packages
+ * @param {string} dependency
+ * @returns {boolean}
+ */
+function hasPackage(packages, dependency) {
+  if (!packages) {
+    return false;
+  }
+  return dependency in packages;
+}
+
+/**
+ * Returns a string corresponding to the framework detected in the cwd.
+ * @returns {Promise<string>}
+ */
+async function detectFramework() {
+  const { dependencies, devDependencies } = await getDependencies(join(process.cwd(), 'package.json'));
+
+  const IS_NEXT = hasFile('next.config.js') || hasFile('next.config.mjs');
+  if (IS_NEXT) {
+    return 'nextjs';
+  }
+
+  const IS_REMIX = hasFile('remix.config.js') || hasFile('remix.config.mjs');
+  if (IS_REMIX) {
+    return 'remix';
+  }
+
+  const IS_VITE = hasPackage(dependencies, 'vite') || hasPackage(devDependencies, 'vite');
+  if (IS_VITE) {
+    return 'vite';
+  }
+
+  throw new Error('unable to determine framework');
+}
+
+/**
+ * Returns the active instance of the provided `configuration`.
+ * @param {import('../utils/getConfiguration.js').Configuration} configuration
+ * @returns {Promise<import('../utils/getConfiguration.js').InstanceConfiguration>}
+ */
+async function getInstanceConfiguration(configuration) {
+  const { activeInstance, instances } = configuration;
+  return instances[activeInstance];
+}
+
+/**
+ * Generates a .env file string.
+ * @param {Record<string, string>} envConfiguration
+ * @returns {string}
+ */
+function buildEnvFile(envConfiguration) {
+  return (
+    Object.entries(envConfiguration)
+      .map(([key, value]) => [key, JSON.stringify(value)].join('='))
+      .join('\n') + '\n'
+  );
+}
+
+/**
+ * Parses the file at `filename` with dotenv.
+ * @param {string} filename
+ * @returns {Promise<import('dotenv').DotenvParseOutput>}
+ */
+async function readEnvFile(filename) {
+  const contents = await readFile(filename, 'utf-8');
+  const envConfig = parse(contents);
+  return envConfig;
+}
+
+/**
+ * Write the provided `config` to the .env file at `filename`, merging with any existing entries.
+ * @param {string} filename
+ * @param {Record<string, string>} config
+ */
+async function mergeEnvFiles(filename, config) {
+  const envFileExists = hasFile(filename);
+  const existingEnv = envFileExists ? await readEnvFile(filename) : {};
+  await writeFile(
+    join(process.cwd(), filename),
+    buildEnvFile({
+      ...existingEnv,
+      ...config,
+    }),
+  );
+}
+
+/**
+ * Installs the monorepo versions of the Clerk dependencies listed in the `package.json` file of the cwd.
+ * @returns {Promise<void>}
+ */
+async function linkDependencies() {
+  const { dependencies } = await getDependencies(join(process.cwd(), 'package.json'));
+  if (!dependencies) {
+    throw new Error('you have no dependencies');
+  }
+  const clerkPackages = await getClerkPackages();
+
+  const dependenciesToBeInstalled = Object.keys(dependencies)
+    .filter(dep => dep in clerkPackages)
+    .map(clerkDep => clerkPackages[clerkDep]);
+
+  const args = ['install', '--no-audit', '--no-fund', ...dependenciesToBeInstalled];
+
+  return new Promise((resolve, reject) => {
+    const child = spawn('npm', args, {
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+        ADBLOCK: '1',
+        DISABLE_OPENCOLLECTIVE: '1',
+      },
+    });
+
+    child.on('close', code => {
+      if (code !== 0) {
+        reject();
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+/**
+ * Installs the monorepo-versions of Clerk dependencies listed in the `package.json` file of the current working
+ * directory, and performs framework configuration tasks necessary for local development with the monorepo packages.
+ * @param {object} args
+ * @param {boolean | undefined} args.js If `false`, do not customize the clerkJSUrl.
+ * @param {boolean | undefined} args.skipInstall If `true`, do not install monorepo versions of packages.
+ */
+export async function setup({ js = true, skipInstall = false }) {
+  if (!skipInstall) {
+    console.log('Installing monorepo versions of Clerk packages from package.json...');
+    await linkDependencies();
+  }
+
+  const config = await getConfiguration();
+  const instance = await getInstanceConfiguration(config);
+
+  const framework = await detectFramework();
+  switch (framework) {
+    case 'nextjs': {
+      console.log('Next.js detected, writing environment variables to .env.local...');
+      await mergeEnvFiles('.env.local', {
+        NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: instance.publishableKey,
+        CLERK_SECRET_KEY: instance.secretKey,
+        ...(js ? { NEXT_PUBLIC_CLERK_JS_URL: 'http://localhost:4000/npm/clerk.browser.js' } : {}),
+      });
+      break;
+    }
+    case 'remix': {
+      console.log('Remix detected, writing environment variables to .env...');
+      await mergeEnvFiles('.env', {
+        CLERK_PUBLISHABLE_KEY: instance.publishableKey,
+        CLERK_SECRET_KEY: instance.secretKey,
+      });
+      break;
+    }
+    case 'vite': {
+      console.log('Vite detected, writing environment variables to .env...');
+      await mergeEnvFiles('.env', {
+        VITE_CLERK_PUBLISHABLE_KEY: instance.publishableKey,
+      });
+
+      if (js) {
+        console.log('Adding clerkJSUrl to ClerkProvider...');
+        const res = await applyCodemod('add-clerkjsurl-to-provider.cjs', [process.cwd()]);
+        if (res.ok === 0) {
+          console.warn('warning: could not find a ClerkProvider to edit. Please add clerkJSUrl manually.');
+        }
+      }
+      break;
+    }
+    default: {
+      throw new Error('unable to determine framework');
+    }
+  }
+}

package/src/commands/watch.js

@@ -0,0 +1,77 @@
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+
+import { getClerkPackages } from '../utils/getClerkPackages.js';
+import { getDependencies } from '../utils/getDependencies.js';
+import { getMonorepoRoot } from '../utils/getMonorepoRoot.js';
+
+/**
+ * Starts long-running watchers for Clerk dependencies.
+ * @param {object} args
+ * @param {boolean | undefined} args.js If `true`, only spawn the builder for `@clerk/clerk-js`.
+ * @returns {Promise<void>}
+ */
+export async function watch({ js }) {
+  const { dependencies, devDependencies } = await getDependencies(join(process.cwd(), 'package.json'));
+  const clerkPackages = Object.keys(await getClerkPackages());
+
+  const packagesInPackageJSON = [...Object.keys(dependencies ?? {}), ...Object.keys(devDependencies ?? {})];
+  const clerkPackagesInPackageJSON = packagesInPackageJSON.filter(p => clerkPackages.includes(p));
+
+  const filterArgs = clerkPackagesInPackageJSON.map(p => `--filter=${p}`);
+
+  const args = ['watch', 'build', ...filterArgs];
+
+  const cwd = await getMonorepoRoot();
+
+  if (js) {
+    return new Promise((resolve, reject) => {
+      const child = spawn(
+        'turbo',
+        ['run', 'dev', '--filter=@clerk/clerk-js', '--', '--env', 'devOrigin=http://localhost:4000'],
+        {
+          cwd,
+          stdio: 'inherit',
+          env: { ...process.env },
+        },
+      );
+
+      child.on('close', code => {
+        if (code !== 0) {
+          reject();
+          return;
+        }
+        resolve();
+      });
+    });
+  }
+
+  if (typeof js === 'undefined') {
+    // On macOS, we spawn a new Terminal.app instance containing the watcher for clerk-js. This is because clerk-js is
+    // not declared as a dependency for any other packages, so Turborepo is unable to automatically start it.
+    if (process.platform === 'darwin') {
+      spawn('osascript', [
+        '-e',
+        `tell app "Terminal" to do script "cd ${cwd} && turbo run dev --filter=@clerk/clerk-js -- --env devOrigin=http://localhost:4000"`,
+      ]);
+    }
+  }
+
+  return new Promise((resolve, reject) => {
+    const child = spawn('turbo', args, {
+      cwd,
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+      },
+    });
+
+    child.on('close', code => {
+      if (code !== 0) {
+        reject();
+        return;
+      }
+      resolve();
+    });
+  });
+}

package/src/utils/getClerkPackages.js

@@ -0,0 +1,23 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, join, posix, resolve } from 'node:path';
+
+import { globby } from 'globby';
+
+/**
+ * Generates an object with keys of package names and values of absolute paths to the package folder.
+ * @returns {Promise<Record<string, string>>}
+ */
+export async function getClerkPackages() {
+  const monorepoRoot = resolve(join(import.meta.dirname, '..', '..', '..', '..'));
+  /** @type {Record<string, string>} */
+  const packages = {};
+  const clerkPackages = await globby([posix.join(monorepoRoot, 'packages', '*', 'package.json'), '!*node_modules*']);
+  for (const packageJSON of clerkPackages) {
+    const { name } = JSON.parse(await readFile(packageJSON, 'utf-8'));
+    if (name) {
+      packages[name] = dirname(packageJSON);
+    }
+  }
+
+  return packages;
+}

package/src/utils/getConfiguration.js

@@ -0,0 +1,31 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * @typedef {object} InstanceConfiguration
+ * @prop {string} secretKey
+ * @prop {string} publishableKey
+ * @prop {string} fapiUrl
+ * @prop {string} bapiUrl
+ */
+
+/**
+ * @typedef {object} Configuration
+ * @prop {string} $schema
+ * @prop {string | null} root
+ * @prop {string} activeInstance
+ * @prop {Record<string, InstanceConfiguration>} instances
+ */
+
+export const CONFIG_FILE = join(homedir(), '.config', 'clerk', 'dev.json');
+
+/**
+ * Gets the contents of the clerk-dev configuration file.
+ * @returns {Promise<Configuration>}
+ */
+export async function getConfiguration() {
+  const configFileJSON = await readFile(CONFIG_FILE, 'utf-8');
+  const configuration = JSON.parse(configFileJSON);
+  return configuration;
+}

package/src/utils/getDependencies.js

@@ -0,0 +1,12 @@
+import { readFile } from 'node:fs/promises';
+
+/**
+ * Gets the `dependencies` and `devDependencies` entries of the provided package.json.
+ * @param {string} pathToPackageJSON
+ * @returns {Promise<{ dependencies?: Record<string, string>, devDependencies?: Record<string, string>}>}
+ */
+export async function getDependencies(pathToPackageJSON) {
+  const packageJSON = await readFile(pathToPackageJSON, 'utf-8');
+  const { dependencies, devDependencies } = JSON.parse(packageJSON);
+  return { dependencies, devDependencies };
+}

package/src/utils/getMonorepoRoot.js

@@ -0,0 +1,21 @@
+import { join, resolve } from 'node:path';
+
+import { getConfiguration } from './getConfiguration.js';
+
+export function getCLIRoot() {
+  return resolve(join(import.meta.dirname, '..', '..', '..', '..'));
+}
+
+/**
+ * Gets the `root` property of the clerk-dev configuration file, falling back to the folder containing the source
+ * for the running instance of clerk-dev.
+ * @returns {Promise<string>}
+ */
+export async function getMonorepoRoot() {
+  const config = await getConfiguration();
+  if (config.root) {
+    return config.root;
+  }
+
+  return getCLIRoot();
+}