@robelest/convex-auth 0.0.4-preview.2 → 0.0.4-preview.21

package/src/cli/index.ts

@@ -1,18 +1,98 @@
-#!/usr/bin/env node
+import { execFileSync } from "child_process";
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+} from "fs";
+import { tmpdir } from "os";
+import path from "path";
 
+import * as p from "@clack/prompts";
 import { Command } from "@commander-js/extra-typings";
-import chalk from "chalk";
-import { execSync } from "child_process";
 import { config as loadEnvFile } from "dotenv";
-import { existsSync, readFileSync, writeFileSync } from "fs";
-import inquirer from "inquirer";
-import path from "path";
 import * as v from "valibot";
+
 import { actionDescription } from "./command";
 import { generateKeys } from "./keys";
 
-const program = new Command()
+// ---------------------------------------------------------------------------
+// Package version
+// ---------------------------------------------------------------------------
+
+function getPackageVersion(): string {
+  // When bundled to dist/bin.cjs the package.json is one level up
+  for (const relative of ["..", "../.."]) {
+    try {
+      const pkgPath = path.resolve(__dirname, relative, "package.json");
+      return JSON.parse(readFileSync(pkgPath, "utf-8")).version;
+    } catch {
+      // try next
+    }
+  }
+  return "unknown";
+}
+
+const version = getPackageVersion();
+
+// ---------------------------------------------------------------------------
+// Package-manager detection
+// ---------------------------------------------------------------------------
+
+type PackageRunner = { cmd: string; args: string[] };
+
+function detectPackageRunner(): PackageRunner {
+  // Walk up from cwd to find lockfiles or packageManager field
+  let dir = process.cwd();
+  const root = path.parse(dir).root;
+
+  while (dir !== root) {
+    const pkgPath = path.join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        if (typeof pkg.packageManager === "string") {
+          const name = pkg.packageManager.split("@")[0];
+          if (name === "pnpm") return { cmd: "pnpm", args: ["exec"] };
+          if (name === "bun") return { cmd: "bunx", args: [] };
+          if (name === "yarn") return { cmd: "yarn", args: ["dlx"] };
+        }
+      } catch {
+        // ignore parse errors
+      }
+    }
+
+    if (existsSync(path.join(dir, "pnpm-lock.yaml")))
+      return { cmd: "pnpm", args: ["exec"] };
+    if (
+      existsSync(path.join(dir, "bun.lockb")) ||
+      existsSync(path.join(dir, "bun.lock"))
+    )
+      return { cmd: "bunx", args: [] };
+    if (existsSync(path.join(dir, "yarn.lock")))
+      return { cmd: "yarn", args: ["dlx"] };
+
+    dir = path.dirname(dir);
+  }
+
+  return { cmd: "npx", args: [] };
+}
+
+const runner = detectPackageRunner();
+
+/** Build the full command + args to invoke `convex` via the detected runner. */
+function convexCmd(...subArgs: string[]): { file: string; args: string[] } {
+  return { file: runner.cmd, args: [...runner.args, "convex", ...subArgs] };
+}
+
+// ---------------------------------------------------------------------------
+// Commander program
+// ---------------------------------------------------------------------------
+
+export const program = new Command()
   .name("@robelest/convex-auth")
+  .version(version)
   .description(
     "Add code and set environment variables for @robelest/convex-auth.\n\n" +
       "Full docs: https://deepwiki.com/robelest/convex-auth",
@@ -34,6 +114,8 @@ program
     actionDescription("Set environment variables on"),
   )
   .action(async (options) => {
+    p.intro("@robelest/convex-auth");
+
     await checkSourceControl(options);
 
     const packageJson = readPackageJson();
@@ -52,7 +134,7 @@ program
     const isExpo = !!(
       packageJson.dependencies?.expo || packageJson.devDependencies?.expo
     );
-    const config = {
+    const config: ProjectConfig = {
       isNextjs,
       isVite,
       isExpo,
@@ -63,31 +145,21 @@ program
     };
 
     // Step 1: Configure SITE_URL
-    // We check for existing config.
-    // We default to localhost and port depending on framework
     await configureSiteUrl(config, options.siteUrl);
 
     // Step 2: Configure private and public key
-    // We ask if we would overwrite existing keys
     await configureKeys(config);
 
-    // Step 3: Change moduleResolution to "bundler"
-    // and turn on skipLibCheck
-    // Skipped if there's no tsconfig.json
+    // Step 3: Change moduleResolution to "bundler" and turn on skipLibCheck
     await modifyTsConfig(config);
 
     // Step 4: Configure convex.config.ts
-    // Ensure the auth component is registered via app.use(auth).
     await configureConvexConfig(config);
 
     // Step 5: Initialize auth.ts
-    // We do nothing if the file already contains the code,
-    // and give instructions otherwise
     await initializeAuth(config);
 
     // Step 6: Configure http.ts
-    // We do nothing if the file already contains the code,
-    // and give instructions otherwise
     await configureHttp(config);
 
     // Extra: Configure providers interactively.
@@ -96,9 +168,13 @@ program
     } else {
       printFinalSuccessMessage(config);
     }
+
+    p.outro("Done!");
   });
 
-program.parse(process.argv);
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
 
 type ProjectConfig = {
   isExpo: boolean;
@@ -121,10 +197,14 @@ type ProjectConfig = {
   step: number;
 };
 
+// ---------------------------------------------------------------------------
+// Step 1: SITE_URL
+// ---------------------------------------------------------------------------
+
 async function configureSiteUrl(config: ProjectConfig, forcedValue?: string) {
   logStep(config, "Configure SITE_URL");
   if (config.isExpo) {
-    logInfo("React Native projects don't require a SITE_URL.");
+    p.log.info("React Native projects don't require a SITE_URL.");
     return;
   }
 
@@ -157,6 +237,10 @@ async function configureSiteUrl(config: ProjectConfig, forcedValue?: string) {
   });
 }
 
+// ---------------------------------------------------------------------------
+// Generic env var configuration
+// ---------------------------------------------------------------------------
+
 async function configureEnvVar(
   config: ProjectConfig,
   variable: {
@@ -174,14 +258,13 @@ async function configureEnvVar(
     await setEnvVar(config, variable.name, variable.forcedValue);
     return;
   }
-  const existing = await backendEnvVar(config, variable.name);
+  const existing = backendEnvVar(config, variable.name);
   if (existing !== "") {
-    if (
-      !(await promptForConfirmation(
-        `The ${printDeployment(config)} already has ${variable.name} configured to ${chalk.bold(existing)}. Do you want to change it?`,
-        { default: false },
-      ))
-    ) {
+    const shouldChange = await promptForConfirmation(
+      `The ${printDeployment(config)} already has ${variable.name} configured to "${existing}". Do you want to change it?`,
+      { default: false },
+    );
+    if (!shouldChange) {
       return;
     }
   }
@@ -192,41 +275,61 @@ async function configureEnvVar(
   await setEnvVar(config, variable.name, chosenValue);
 }
 
+// ---------------------------------------------------------------------------
+// Step 2: Keys
+// ---------------------------------------------------------------------------
+
 async function configureKeys(config: ProjectConfig) {
-  logStep(config, "Configure private and public key");
-  const { JWT_PRIVATE_KEY, JWKS } = await generateKeys();
-  // TODO: We should just list all the 3 env vars in one command
-  // to speed things up, but the convex CLI doesn't quote the
-  // values correctly right now, so we can't.
-  const existingPrivateKey = await backendEnvVar(config, "JWT_PRIVATE_KEY");
-  const existingJwks = await backendEnvVar(config, "JWKS");
-  if (existingPrivateKey !== "" || existingJwks !== "") {
-    if (
-      !(await promptForConfirmation(
-        `The ${printDeployment(config)} already has JWT_PRIVATE_KEY or JWKS configured. Overwrite them?`,
-        { default: false },
-      ))
-    ) {
+  logStep(config, "Configure signing and encryption keys");
+  const { JWT_PRIVATE_KEY, JWKS, AUTH_SECRET_ENCRYPTION_KEY } =
+    await generateKeys();
+  const existingPrivateKey = backendEnvVar(config, "JWT_PRIVATE_KEY");
+  const existingJwks = backendEnvVar(config, "JWKS");
+  const existingSecretEncryptionKey = backendEnvVar(
+    config,
+    "AUTH_SECRET_ENCRYPTION_KEY",
+  );
+  if (
+    existingPrivateKey !== "" ||
+    existingJwks !== "" ||
+    existingSecretEncryptionKey !== ""
+  ) {
+    const shouldOverwrite = await promptForConfirmation(
+      `The ${printDeployment(config)} already has JWT_PRIVATE_KEY, JWKS, or AUTH_SECRET_ENCRYPTION_KEY configured. Overwrite them?`,
+      { default: false },
+    );
+    if (!shouldOverwrite) {
       return;
     }
   }
-  // TODO: We should set both env vars in one command, but the convex CLI doesn't
-  // support setting multiple env vars.
-  await setEnvVar(config, "JWT_PRIVATE_KEY", JWT_PRIVATE_KEY, {
-    hideValue: true,
-  });
-  await setEnvVar(config, "JWKS", JWKS, { hideValue: true });
+  // Use --from-file to avoid shell quoting issues with multiline values
+  await setEnvVarFromFile(config, "JWT_PRIVATE_KEY", JWT_PRIVATE_KEY);
+  await setEnvVarFromFile(config, "JWKS", JWKS);
+  await setEnvVar(
+    config,
+    "AUTH_SECRET_ENCRYPTION_KEY",
+    AUTH_SECRET_ENCRYPTION_KEY,
+    {
+      hideValue: true,
+    },
+  );
 }
 
-async function backendEnvVar(config: ProjectConfig, name: string) {
-  return (
-    execSync(`npx convex env get ${deploymentOptions(config)} ${name}`, {
-      stdio: "pipe",
-    })
-      .toString()
-      // Remove trailing newline
-      .slice(0, -1)
+// ---------------------------------------------------------------------------
+// Convex env helpers (no shell injection — argument arrays only)
+// ---------------------------------------------------------------------------
+
+function backendEnvVar(config: ProjectConfig, name: string): string {
+  const { file, args } = convexCmd(
+    "env",
+    "get",
+    ...deploymentArgs(config),
+    name,
   );
+  return execFileSync(file, args, {
+    stdio: "pipe",
+    encoding: "utf-8",
+  }).slice(0, -1);
 }
 
 async function setEnvVar(
@@ -235,59 +338,91 @@ async function setEnvVar(
   value: string,
   options?: { hideValue: boolean },
 ) {
-  const valueEscaped = value.replace(/"/g, '\\"');
-  execSync(
-    `npx convex env set ${deploymentOptions(config)} -- ${name} "${valueEscaped}"`,
-    {
-      stdio: options?.hideValue ? "ignore" : "inherit",
-    },
+  const { file, args } = convexCmd(
+    "env",
+    "set",
+    ...deploymentArgs(config),
+    "--",
+    name,
+    value,
   );
+  execFileSync(file, args, {
+    stdio: options?.hideValue ? "ignore" : "inherit",
+  });
   if (options?.hideValue) {
-    logSuccess(
-      `Successfully set ${chalk.bold(name)} (on ${printDeployment(config)})`,
-    );
+    p.log.success(`Successfully set ${name} (on ${printDeployment(config)})`);
   }
 }
 
-function deploymentOptions(config: ProjectConfig) {
-  const {
-    deployment: {
-      options: { adminKey },
-    },
-  } = config;
-  const adminKeyOption =
-    adminKey !== undefined ? `--admin-key '${adminKey}' ` : "";
-  return adminKeyOption + deploymentNameOptions(config);
+/**
+ * Write value to a temp file and use `convex env set KEY --from-file tmpfile`.
+ * This avoids shell-quoting issues with multiline values like private keys.
+ */
+async function setEnvVarFromFile(
+  config: ProjectConfig,
+  name: string,
+  value: string,
+) {
+  const tmpDir = mkdtempSync(path.join(tmpdir(), "convex-auth-"));
+  const tmpFile = path.join(tmpDir, `${name}.tmp`);
+  try {
+    writeFileSync(tmpFile, value, "utf-8");
+    const { file, args } = convexCmd(
+      "env",
+      "set",
+      ...deploymentArgs(config),
+      name,
+      "--from-file",
+      tmpFile,
+    );
+    execFileSync(file, args, { stdio: "ignore" });
+    p.log.success(`Successfully set ${name} (on ${printDeployment(config)})`);
+  } finally {
+    try {
+      unlinkSync(tmpFile);
+    } catch {
+      // cleanup is best-effort
+    }
+  }
 }
 
-function deploymentNameOptions(config: ProjectConfig) {
+function deploymentArgs(config: ProjectConfig): string[] {
   const {
     deployment: {
-      options: { url, prod, previewName, deploymentName },
+      options: { adminKey, url, prod, previewName, deploymentName },
     },
   } = config;
-  if (url) {
-    return `--url ${url}`;
-  } else if (prod) {
-    return "--prod";
-  } else if (previewName) {
-    return `--preview-name ${previewName}`;
-  } else if (deploymentName) {
-    return `--deployment-name ${deploymentName}`;
-  } else {
-    return "";
+  const args: string[] = [];
+
+  if (adminKey !== undefined) {
+    args.push("--admin-key", adminKey);
   }
+
+  const selectionArgs =
+    [
+      url ? ["--url", url] : null,
+      prod ? ["--prod"] : null,
+      previewName ? ["--preview-name", previewName] : null,
+      deploymentName ? ["--deployment-name", deploymentName] : null,
+    ].find((s): s is string[] => s !== null) ?? [];
+
+  args.push(...selectionArgs);
+  return args;
 }
 
-function printDeployment(config: ProjectConfig) {
+function printDeployment(config: ProjectConfig): string {
   const { name, type } = config.deployment;
   return (
-    (type !== null ? `${chalk.bold(type)} ` : "") +
+    (type !== null ? `${type} ` : "") +
     "deployment" +
-    (name !== null ? ` ${chalk.bold(name)}` : "")
+    (name !== null ? ` ${name}` : "")
   );
 }
 
+// ---------------------------------------------------------------------------
+// Step 3: tsconfig
+// ---------------------------------------------------------------------------
+
 // Match `"compilerOptions": {"`
 // ignore comments after the bracket
 // and capture the space between the bracket/last comment
@@ -331,13 +466,13 @@ async function modifyTsConfig(config: ProjectConfig) {
     if (existsSync(projectLevelTsConfigPath)) {
       if (config.isExpo) {
         writeFileSync(tsConfigPath, validTsConfig);
-        logSuccess(`Added ${chalk.bold(tsConfigPath)}`);
+        p.log.success(`Added ${tsConfigPath}`);
         return;
       }
       // else assume that the project-level tsconfig already
       // has the right settings, which is true for Vite and Next.js
     }
-    logInfo(`No ${chalk.bold(tsConfigPath)} found. Skipping.`);
+    p.log.info(`No ${tsConfigPath} found. Skipping.`);
     return;
   }
   const existingTsConfig = readFileSync(tsConfigPath, "utf8");
@@ -351,14 +486,12 @@ async function modifyTsConfig(config: ProjectConfig) {
     /Bundler/i.test(existingModuleResolution) &&
     existingSkipLibCheck === "true"
   ) {
-    logSuccess(`The ${chalk.bold(tsConfigPath)} is already set up.`);
+    p.log.success(`The ${tsConfigPath} is already set up.`);
     return;
   }
 
   if (!compilerOptionsPattern.test(existingTsConfig)) {
-    logInfo(
-      `Modify your ${chalk.bold(tsConfigPath)} to include the following:`,
-    );
+    p.log.info(`Modify your ${tsConfigPath} to include the following:`);
     const source = `\
   {
     "compilerOptions": {
@@ -367,7 +500,7 @@ async function modifyTsConfig(config: ProjectConfig) {
     }
   }
     `;
-    print(indent(`\n${source}\n`));
+    p.log.message(indent(`\n${source}\n`));
     await promptForConfirmationOrExit("Ready to continue?");
   }
   const changedTsConfig = addCompilerOption(
@@ -382,7 +515,7 @@ async function modifyTsConfig(config: ProjectConfig) {
     '"skipLibCheck": true',
   );
   writeFileSync(tsConfigPath, changedTsConfig);
-  logSuccess(`Modified ${chalk.bold(tsConfigPath)}`);
+  p.log.success(`Modified ${tsConfigPath}`);
 }
 
 function addCompilerOption(
@@ -398,6 +531,10 @@ function addCompilerOption(
   }
 }
 
+// ---------------------------------------------------------------------------
+// Step 4: convex.config
+// ---------------------------------------------------------------------------
+
 async function configureConvexConfig(config: ProjectConfig) {
   logStep(config, "Configure convex config file");
   const sourceTemplate = `\
@@ -412,16 +549,16 @@ export default app;
 `;
   const source = templateToSource(sourceTemplate);
   const convexConfigPath = path.join(config.convexFolderPath, "convex.config");
-  const existingConfigPath = await existingNonEmptySourcePath(convexConfigPath);
+  const existingConfigPath = existingNonEmptySourcePath(convexConfigPath);
   if (existingConfigPath !== null) {
     const existingConfig = readFileSync(existingConfigPath, "utf8");
     if (doesAlreadyMatchTemplate(existingConfig, sourceTemplate)) {
-      logSuccess(`The ${chalk.bold(existingConfigPath)} is already set up.`);
+      p.log.success(`The ${existingConfigPath} is already set up.`);
     } else {
-      logInfo(
-        `You already have a ${chalk.bold(existingConfigPath)}, make sure it registers the auth component like this:`,
+      p.log.info(
+        `You already have a ${existingConfigPath}, make sure it registers the auth component like this:`,
       );
-      print(indent(`\n${source}\n`));
+      p.log.message(indent(`\n${source}\n`));
       await promptForConfirmationOrExit("Ready to continue?");
     }
   } else {
@@ -429,17 +566,21 @@ export default app;
       ? `${convexConfigPath}.ts`
       : `${convexConfigPath}.js`;
     writeFileSync(newConfigPath, source);
-    logSuccess(`Created ${chalk.bold(newConfigPath)}`);
+    p.log.success(`Created ${newConfigPath}`);
   }
 }
 
+// ---------------------------------------------------------------------------
+// Step 5: auth.ts
+// ---------------------------------------------------------------------------
+
 async function initializeAuth(config: ProjectConfig) {
   logStep(config, "Initialize auth file");
   const sourceTemplate = `\
-import { Auth } from "@robelest/convex-auth/component";
+import { createAuth } from "@robelest/convex-auth/component";
 import { components } from "./_generated/api";
 
-const auth = new Auth(components.auth, {$$
+const auth = createAuth(components.auth, {$$
   providers: [$$],$$
 });
 
@@ -448,16 +589,16 @@ export const { signIn, signOut, store } = auth;
 `;
   const source = templateToSource(sourceTemplate);
   const authPath = path.join(config.convexFolderPath, "auth");
-  const existingAuthPath = await existingNonEmptySourcePath(authPath);
+  const existingAuthPath = existingNonEmptySourcePath(authPath);
   if (existingAuthPath !== null) {
     const existingAuth = readFileSync(existingAuthPath, "utf8");
     if (doesAlreadyMatchTemplate(existingAuth, sourceTemplate)) {
-      logSuccess(`The ${chalk.bold(existingAuthPath)} is already set up.`);
+      p.log.success(`The ${existingAuthPath} is already set up.`);
     } else {
-      logInfo(
-        `You already have a ${chalk.bold(existingAuthPath)}, make sure it initializes \`Auth\` like this:`,
+      p.log.info(
+        `You already have a ${existingAuthPath}, make sure it initializes auth with \`createAuth\` like this:`,
       );
-      print(indent(`\n${source}\n`));
+      p.log.message(indent(`\n${source}\n`));
       await promptForConfirmationOrExit("Ready to continue?");
     }
   } else {
@@ -465,10 +606,14 @@ export const { signIn, signOut, store } = auth;
       ? `${authPath}.ts`
       : `${authPath}.js`;
     writeFileSync(newAuthPath, source);
-    logSuccess(`Created ${chalk.bold(newAuthPath)}`);
+    p.log.success(`Created ${newAuthPath}`);
   }
 }
 
+// ---------------------------------------------------------------------------
+// Step 6: http.ts
+// ---------------------------------------------------------------------------
+
 async function configureHttp(config: ProjectConfig) {
   logStep(config, "Configure http file");
   const sourceTemplate = `\
@@ -483,16 +628,16 @@ export default http;
 `;
   const source = templateToSource(sourceTemplate);
   const httpPath = path.join(config.convexFolderPath, "http");
-  const existingHttpPath = await existingNonEmptySourcePath(httpPath);
+  const existingHttpPath = existingNonEmptySourcePath(httpPath);
   if (existingHttpPath !== null) {
     const existingHttp = readFileSync(existingHttpPath, "utf8");
     if (doesAlreadyMatchTemplate(existingHttp, sourceTemplate)) {
-      logSuccess(`The ${chalk.bold(existingHttpPath)} is already set up.`);
+      p.log.success(`The ${existingHttpPath} is already set up.`);
     } else {
-      logInfo(
-        `You already have a ${chalk.bold(existingHttpPath)}, make sure it includes the call to \`auth.http.add\`:`,
+      p.log.info(
+        `You already have a ${existingHttpPath}, make sure it includes the call to \`auth.http.add\`:`,
       );
-      print(indent(`\n${source}\n`));
+      p.log.message(indent(`\n${source}\n`));
       await promptForConfirmationOrExit("Ready to continue?");
     }
   } else {
@@ -500,10 +645,14 @@ export default http;
       ? `${httpPath}.ts`
       : `${httpPath}.js`;
     writeFileSync(newHttpPath, source);
-    logSuccess(`Created ${chalk.bold(newHttpPath)}`);
+    p.log.success(`Created ${newHttpPath}`);
   }
 }
 
+// ---------------------------------------------------------------------------
+// Extra: --variables
+// ---------------------------------------------------------------------------
+
 const VariablesSchema = v.object({
   help: v.optional(v.string()),
   providers: v.array(
@@ -522,23 +671,30 @@ const VariablesSchema = v.object({
 });
 
 async function configureOtherVariables(config: ProjectConfig, json: string) {
-  const variables = v.parse(VariablesSchema, JSON.parse(json));
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch (err) {
+    logErrorAndExit(
+      "The --variables flag must be valid JSON.",
+      err instanceof Error ? err.message : String(err),
+    );
+  }
+
+  const variables = v.parse(VariablesSchema, parsed);
   logStep(config, "Configure extra environment variables");
-  // Ex: The default setup includes sign-in with GitHub OAuth
-  // and sending magic links via Resend.
   if (variables.help !== undefined) {
-    print(variables.help);
+    p.log.message(variables.help);
   }
   for (const provider of variables.providers) {
-    if (
-      !(await promptForConfirmation(
-        `Do you want to configure ${provider.name}?`,
-      ))
-    ) {
+    const shouldConfigure = await promptForConfirmation(
+      `Do you want to configure ${provider.name}?`,
+    );
+    if (!shouldConfigure) {
       continue;
     }
     if (provider.help !== undefined) {
-      print(provider.help);
+      p.log.message(provider.help);
     }
     for (const variable of provider.variables) {
       await configureEnvVar(config, {
@@ -548,11 +704,15 @@ async function configureOtherVariables(config: ProjectConfig, json: string) {
     }
   }
   if (variables.success !== undefined) {
-    logSuccess(variables.success);
+    p.log.success(variables.success);
   }
 }
 
-function doesAlreadyMatchTemplate(existing: string, template: string) {
+// ---------------------------------------------------------------------------
+// Template helpers
+// ---------------------------------------------------------------------------
+
+export function doesAlreadyMatchTemplate(existing: string, template: string) {
   const regex = new RegExp(
     template
       .replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
@@ -563,29 +723,34 @@ function doesAlreadyMatchTemplate(existing: string, template: string) {
   return regex.test(existing);
 }
 
-function templateToSource(template: string) {
+export function templateToSource(template: string) {
   return template.replace(/\$\$/g, "");
 }
 
-async function existingNonEmptySourcePath(path: string) {
-  return (await existsAndNotEmpty(`${path}.ts`))
-    ? `${path}.ts`
-    : (await existsAndNotEmpty(`${path}.js`))
-      ? `${path}.js`
+function existingNonEmptySourcePath(filePath: string): string | null {
+  return existsAndNotEmpty(`${filePath}.ts`)
+    ? `${filePath}.ts`
+    : existsAndNotEmpty(`${filePath}.js`)
+      ? `${filePath}.js`
       : null;
 }
 
-async function existsAndNotEmpty(path: string) {
-  return existsSync(path) && readFileSync(path, "utf8").trim() !== "";
+function existsAndNotEmpty(filePath: string): boolean {
+  return existsSync(filePath) && readFileSync(filePath, "utf8").trim() !== "";
 }
 
+// ---------------------------------------------------------------------------
+// Logging
+// ---------------------------------------------------------------------------
+
 function logStep(config: ProjectConfig, message: string) {
-  if (config.step > 1) {
-    print();
-  }
-  logInfo(chalk.bold(`Step ${config.step++}: ${message}`));
+  p.log.step(`Step ${config.step++}: ${message}`);
 }
 
+// ---------------------------------------------------------------------------
+// Source control check
+// ---------------------------------------------------------------------------
+
 async function checkSourceControl(options: {
   skipGitCheck?: boolean;
   allowDirtyGitState?: boolean;
@@ -595,14 +760,25 @@ async function checkSourceControl(options: {
   }
   const isGit = existsSync(".git");
   if (isGit) {
-    const gitStatus = execSync("git status --porcelain").toString();
+    let gitStatus: string;
+    try {
+      gitStatus = execFileSync("git", ["status", "--porcelain"], {
+        encoding: "utf-8",
+      });
+    } catch {
+      // git not available — skip check
+      return;
+    }
     const changedFiles = gitStatus
       .split("\n")
       .filter(
-        (line) => !/\bpackage(-lock)?.json/.test(line) && line.length > 0,
+        (line) =>
+          !/\bpackage(-lock)?.json/.test(line) &&
+          !/\benv\.d\.ts$/.test(line) &&
+          line.length > 0,
       );
     if (changedFiles.length > 0) {
-      logError(
+      p.log.error(
         "There are unstaged or uncommitted changes in the working directory. " +
           "Please commit or stash them before proceeding.",
       );
@@ -612,13 +788,17 @@ async function checkSourceControl(options: {
     if (options.skipGitCheck) {
       return;
     }
-    logWarning(
+    p.log.warn(
       "No source control detected. We strongly recommend committing the current state of your code before proceeding.",
     );
     await promptForConfirmationOrExit("Continue anyway?");
   }
 }
 
+// ---------------------------------------------------------------------------
+// Project file readers
+// ---------------------------------------------------------------------------
+
 type PackageJSON = { __isPackageJSON: true; [key: string]: any };
 
 function readPackageJson(): PackageJSON {
@@ -652,7 +832,11 @@ function readConvexJson(): ConvexJSON {
   }
 }
 
-function readConvexDeployment(options: {
+// ---------------------------------------------------------------------------
+// Deployment selection
+// ---------------------------------------------------------------------------
+
+export function readConvexDeployment(options: {
   url?: string;
   adminKey?: string;
   prod?: boolean;
@@ -660,30 +844,45 @@ function readConvexDeployment(options: {
   deploymentName?: string;
 }) {
   const { adminKey, url, prod, previewName, deploymentName } = options;
-  const adminKeyName = adminKey ? deploymentNameFromAdminKey(adminKey) : null;
-  const adminKeyType = adminKey ? deploymentTypeFromAdminKey(adminKey) : null;
+
   if (url) {
-    return { name: adminKeyName ?? url, type: adminKeyType, options };
-  } else if (prod) {
-    return { name: adminKeyName, type: "prod", options };
-  }
-  if (previewName) {
-    return { name: previewName, type: "preview", options };
-  }
-  if (deploymentName) {
-    return { name: deploymentName, type: adminKeyType, options };
+    return {
+      name: url,
+      type: null,
+      options,
+    };
   }
-  if (adminKey) {
-    return { name: adminKeyName, type: adminKeyType, options };
+
+  const adminKeyName = adminKey ? deploymentNameFromAdminKey(adminKey) : null;
+  const adminKeyType = adminKey ? deploymentTypeFromAdminKey(adminKey) : null;
+
+  const explicitSelection = [
+    prod ? { name: adminKeyName, type: "prod" as const } : null,
+    previewName ? { name: previewName, type: "preview" as const } : null,
+    deploymentName ? { name: deploymentName, type: adminKeyType } : null,
+    adminKey ? { name: adminKeyName, type: adminKeyType } : null,
+  ].find(
+    (
+      selection,
+    ): selection is {
+      name: string | null;
+      type: string | null;
+    } => selection !== null,
+  );
+
+  if (explicitSelection !== undefined) {
+    return { ...explicitSelection, options };
   }
+
   loadEnvFile({ path: ".env.local" });
   loadEnvFile();
   if (process.env.CONVEX_DEPLOYMENT) {
+    const type = getDeploymentTypeFromConfiguredDeployment(
+      process.env.CONVEX_DEPLOYMENT,
+    );
     return {
       name: stripDeploymentTypePrefix(process.env.CONVEX_DEPLOYMENT),
-      type: getDeploymentTypeFromConfiguredDeployment(
-        process.env.CONVEX_DEPLOYMENT,
-      ),
+      type,
       options,
     };
   }
@@ -696,50 +895,52 @@ function readConvexDeployment(options: {
 // NOTE: CONVEX CLI DEP
 // Given a deployment string like "dev:tall-forest-1234"
 // returns only the slug "tall-forest-1234".
-// If there's no prefix returns the original string.
 export function stripDeploymentTypePrefix(deployment: string) {
-  return deployment.split(":").at(-1)!;
+  const [type, name] = deployment.split(":");
+  if ((type !== "prod" && type !== "dev" && type !== "preview") || !name) {
+    logErrorAndExit(
+      "Invalid CONVEX_DEPLOYMENT.",
+      'Expected a typed deployment like "dev:my-deployment", "prod:my-deployment", or "preview:my-deployment".',
+    );
+  }
+  return name;
 }
 
 // NOTE: CONVEX CLI DEP
-// Handling legacy CONVEX_DEPLOYMENT without type prefix as well
 function getDeploymentTypeFromConfiguredDeployment(raw: string) {
   const typeRaw = raw.split(":")[0];
-  const type =
-    typeRaw === "prod" || typeRaw === "dev" || typeRaw === "preview"
-      ? typeRaw
-      : null;
-  return type;
+  if (typeRaw === "prod" || typeRaw === "dev" || typeRaw === "preview") {
+    return typeRaw;
+  }
+  logErrorAndExit(
+    "Invalid CONVEX_DEPLOYMENT.",
+    'Expected a typed deployment like "dev:my-deployment", "prod:my-deployment", or "preview:my-deployment".',
+  );
 }
 
 // NOTE: CONVEX CLI DEP
 function deploymentNameFromAdminKey(adminKey: string) {
   const parts = adminKey.split("|");
-  if (parts.length === 1) {
-    return null;
-  }
-  if (isPreviewDeployKey(adminKey)) {
-    // Preview deploy keys do not contain a deployment name.
-    return null;
-  }
-  return stripDeploymentTypePrefix(parts[0]);
+  const hasDeployment = parts.length > 1;
+  return hasDeployment && !isPreviewDeployKey(adminKey)
+    ? stripDeploymentTypePrefix(parts[0])
+    : null;
 }
 
-// NOTE: CONVEX CLI DEP - but modified to not default to "prod"
-//
-// For current keys returns prod|dev|preview,
-// for legacy keys returns "prod".
+// NOTE: CONVEX CLI DEP
 // Examples:
 //  "prod:deploymentName|key" -> "prod"
 //  "preview:deploymentName|key" -> "preview"
 //  "dev:deploymentName|key" -> "dev"
-//  "key" -> "prod"
 export function deploymentTypeFromAdminKey(adminKey: string) {
-  const parts = adminKey.split(":");
-  if (parts.length === 1) {
-    return null;
+  const type = adminKey.split(":")[0];
+  if (type === "prod" || type === "dev" || type === "preview") {
+    return type;
   }
-  return parts.at(0)!;
+  logErrorAndExit(
+    "Invalid admin key.",
+    'Expected a typed key like "dev:deployment|...", "prod:deployment|...", or "preview:...".',
+  );
 }
 
 // NOTE: CONVEX CLI DEP
@@ -757,11 +958,16 @@ export function isPreviewDeployKey(adminKey: string) {
   return prefixParts[0] === "preview" && prefixParts.length === 3;
 }
 
+// ---------------------------------------------------------------------------
+// Prompts (using @clack/prompts, with TTY detection on stdin)
+// ---------------------------------------------------------------------------
+
 async function promptForConfirmationOrExit(
   message: string,
   options: { default?: boolean } = {},
 ) {
   if (!(await promptForConfirmation(message, options))) {
+    p.cancel("Setup cancelled.");
     process.exit(1);
   }
 }
@@ -769,17 +975,17 @@ async function promptForConfirmationOrExit(
 async function promptForConfirmation(
   message: string,
   options: { default?: boolean } = {},
-) {
-  if (process.stdout.isTTY) {
-    const { confirmed } = await inquirer.prompt<{ confirmed: boolean }>([
-      {
-        type: "confirm",
-        name: "confirmed",
-        message,
-        default: options.default ?? true,
-      },
-    ]);
-    return confirmed;
+): Promise<boolean> {
+  if (process.stdin.isTTY) {
+    const result = await p.confirm({
+      message,
+      initialValue: options.default ?? true,
+    });
+    if (p.isCancel(result)) {
+      p.cancel("Setup cancelled.");
+      process.exit(1);
+    }
+    return result;
   } else {
     return options.default ?? true;
   }
@@ -787,19 +993,30 @@ async function promptForConfirmation(
 
 async function promptForInput(
   message: string,
-  options: { default?: string; validate?: (input: string) => true | string },
-) {
-  if (process.stdout.isTTY) {
-    const { input } = await inquirer.prompt<{ input: string }>([
-      {
-        type: "input",
-        name: "input",
-        message,
-        default: options.default,
-        validate: options.validate,
-      },
-    ]);
-    return input;
+  options: {
+    default?: string;
+    validate?: (input: string) => true | string;
+  },
+): Promise<string> {
+  if (process.stdin.isTTY) {
+    const result = await p.text({
+      message,
+      defaultValue: options.default,
+      placeholder: options.default,
+      validate: options.validate
+        ? (val: string | undefined) => {
+            if (val === undefined) return "Input is required";
+            const check = options.validate!(val);
+            if (check === true) return undefined;
+            return check;
+          }
+        : undefined,
+    });
+    if (p.isCancel(result)) {
+      p.cancel("Setup cancelled.");
+      process.exit(1);
+    }
+    return result;
   } else {
     if (options.default !== undefined) {
       return options.default;
@@ -811,56 +1028,47 @@ async function promptForInput(
   }
 }
 
+// ---------------------------------------------------------------------------
+// Final success message
+// ---------------------------------------------------------------------------
+
 function printFinalSuccessMessage(config: ProjectConfig) {
   const isProd = config.deployment.type === "prod";
   const deploymentName = config.deployment.name ?? "your deployment";
 
   if (isProd) {
-    logSuccess(`Production setup complete for ${deploymentName}.`);
-    print("");
-    print(`  Full docs: ${chalk.cyan("https://deepwiki.com/robelest/convex-auth")}`);
+    p.log.success(`Production setup complete for ${deploymentName}.`);
+    p.log.message("  Full docs: https://deepwiki.com/robelest/convex-auth");
   } else {
-    logSuccess(`Setup complete for ${deploymentName}.`);
-    print("");
-    print(`  ${chalk.bold("To set up production")}, run this command with your production URL:`);
-    print(`    ${chalk.cyan("npx @robelest/convex-auth --prod --site-url \"https://myapp.com\"")}`);
-    print("");
-    print(`  ${chalk.bold("Don't forget")} to set provider secrets on production too:`);
-    print(`    ${chalk.grey("npx convex env set --prod AUTH_GITHUB_ID \"...\"")}`);
-    print(`    ${chalk.grey("npx convex env set --prod AUTH_GITHUB_SECRET \"...\"")}`);
-    print("");
-    print(`  Full docs: ${chalk.cyan("https://deepwiki.com/robelest/convex-auth")}`);
+    p.log.success(`Setup complete for ${deploymentName}.`);
+    p.log.message("");
+    p.log.message(
+      "  To set up production, run this command with your production URL:",
+    );
+    p.log.message(
+      '    npx @robelest/convex-auth --prod --site-url "https://myapp.com"',
+    );
+    p.log.message("");
+    p.log.message("  Don't forget to set provider secrets on production too:");
+    p.log.message('    npx convex env set --prod AUTH_GITHUB_ID "..."');
+    p.log.message('    npx convex env set --prod AUTH_GITHUB_SECRET "..."');
+    p.log.message("");
+    p.log.message("  Full docs: https://deepwiki.com/robelest/convex-auth");
   }
 }
 
+// ---------------------------------------------------------------------------
+// Error helpers
+// ---------------------------------------------------------------------------
+
 function logErrorAndExit(message: string, error?: string): never {
-  logError(message, error);
+  p.log.error(`${message}${error !== undefined ? `\n  Error: ${error}` : ""}`);
   process.exit(1);
 }
 
-function logError(message: string, error?: string) {
-  print(
-    `${chalk.red(`✖`)} ${indent(message)}${
-      error !== undefined ? `\n  ${chalk.grey(`Error: ${indent(error)}`)}` : ""
-    }`,
-  );
-}
-
-function logWarning(message: string) {
-  print(`${chalk.yellow.bold(`!`)} ${indent(message)}`);
-}
-
-function logInfo(message: string) {
-  print(`${chalk.blue.bold(`i`)} ${indent(message)}`);
-}
-
-function logSuccess(message: string) {
-  print(`${chalk.green(`✔`)} ${indent(message)}`);
-}
-
-function print(message?: string) {
-  process.stderr.write((message ?? "") + "\n");
-}
+// ---------------------------------------------------------------------------
+// String helpers
+// ---------------------------------------------------------------------------
 
 function indent(string: string) {
   return string.replace(/^/gm, "  ").slice(2);