refactor(cli): centralize settings and modernize ESM module system (#4)

Author: nicknisi

packages/cli/bin.ts

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 import { satisfies } from 'semver';
-import { red } from './src/utils/logging';
+import { red } from './src/utils/logging.js';
+import { getSettings } from './src/lib/settings.js';
 
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import chalk from 'chalk';
 
-const NODE_VERSION_RANGE = '>=18.17.0';
+const NODE_VERSION_RANGE = getSettings().nodeVersion;
 
 // Have to run this above the other imports because they are importing clack that
 // has the problematic imports.
@@ -17,10 +18,10 @@ if (!satisfies(process.version, NODE_VERSION_RANGE)) {
   process.exit(1);
 }
 
-import type { WizardOptions } from './src/utils/types';
-import { runWizard } from './src/run';
-import { isNonInteractiveEnvironment } from './src/utils/environment';
-import clack from './src/utils/clack';
+import type { WizardOptions } from './src/utils/types.js';
+import { runWizard } from './src/run.js';
+import { isNonInteractiveEnvironment } from './src/utils/environment.js';
+import clack from './src/utils/clack.js';
 
 // E2E tests removed - no mock server needed
 
@@ -142,4 +143,4 @@ yargs(hideBin(process.argv))
   .alias('help', 'h')
   .version()
   .alias('version', 'v')
-  .wrap(process.stdout.isTTY ? yargs.terminalWidth() : 80).argv;
+  .wrap(process.stdout.isTTY && process.stdout.columns ? process.stdout.columns : 80).argv;

packages/cli/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@workos/authkit-wizard",
   "version": "1.0.0",
+  "type": "module",
   "description": "CLI wizard for automatically setting up WorkOS AuthKit in your project",
   "keywords": [
     "workos",
@@ -22,6 +23,7 @@
   "files": [
     "dist/bin.*",
     "dist/src",
+    "dist/settings.json",
     ".claude-plugin",
     "skills",
     "package.json",
@@ -37,7 +39,7 @@
     "@clack/core": "^0.3.4",
     "@clack/prompts": "0.7.0",
     "axios": "1.7.4",
-    "chalk": "^2.4.1",
+    "chalk": "^5.4.1",
     "fast-glob": "^3.3.3",
     "glob": "9.3.5",
     "inquirer": "^6.2.0",
@@ -64,7 +66,7 @@
     "@types/opn": "5.1.0",
     "@types/rimraf": "^3.0.2",
     "@types/semver": "^7.3.7",
-    "@types/yargs": "^16.0.9",
+    "@types/yargs": "^17.0.33",
     "@typescript-eslint/eslint-plugin": "^5.13.0",
     "@typescript-eslint/parser": "^5.13.0",
     "@vitest/ui": "^4.0.17",
@@ -94,7 +96,7 @@
     "prebuild": "pnpm clean",
     "build:watch": "pnpm tsc -w",
     "build": "pnpm tsc",
-    "postbuild": "chmod +x ./dist/bin.js && cp -r scripts/** dist",
+    "postbuild": "chmod +x ./dist/bin.js && cp settings.json dist/ && cp -r scripts/** dist",
     "lint": "pnpm lint:prettier && pnpm lint:eslint",
     "lint:prettier": "prettier --check \"{lib,src,test}/**/*.ts\"",
     "lint:eslint": "eslint . --cache --format stylish",

packages/cli/settings.json

@@ -0,0 +1,62 @@
+{
+  "version": "1.0.0",
+  "model": "claude-opus-4-5-20251101",
+  "gateway": {
+    "development": "http://localhost:8000",
+    "production": "https://llm-gateway.example.com",
+    "port": 8000
+  },
+  "api": {
+    "workos": {
+      "development": "http://localhost:8000",
+      "production": "https://api.workos.com"
+    },
+    "dashboard": {
+      "development": "http://localhost:3000",
+      "production": "https://dashboard.workos.com"
+    }
+  },
+  "telemetry": {
+    "enabled": false,
+    "eventName": "wizard interaction"
+  },
+  "nodeVersion": ">=18.17.0",
+  "logging": {
+    "logFile": "/tmp/authkit-wizard.log",
+    "debugMode": false
+  },
+  "documentation": {
+    "workosDocsUrl": "https://workos.com/docs/authkit",
+    "dashboardUrl": "https://dashboard.workos.com",
+    "issuesUrl": "https://github.com/workos/authkit-wizard/issues"
+  },
+  "frameworks": {
+    "nextjs": {
+      "port": 3000,
+      "callbackPath": "/api/auth/callback"
+    },
+    "react": {
+      "port": 5173,
+      "callbackPath": "/callback"
+    },
+    "tanstackStart": {
+      "port": 3000,
+      "callbackPath": "/api/auth/callback"
+    },
+    "reactRouter": {
+      "port": 5173,
+      "callbackPath": "/callback"
+    },
+    "vanillaJs": {
+      "port": 5173,
+      "callbackPath": "/callback"
+    }
+  },
+  "legacy": {
+    "oauthPort": 8239
+  },
+  "branding": {
+    "showAsciiArt": true,
+    "asciiArt": "░██       ░██                     ░██         ░██████     ░██████      \n░██       ░██                     ░██        ░██   ░██   ░██   ░██     \n░██  ░██  ░██  ░███████  ░██░████ ░██    ░██░██     ░██ ░██            \n░██ ░████ ░██ ░██    ░██ ░███     ░██   ░██ ░██     ░██  ░████████     \n░██░██ ░██░██ ░██    ░██ ░██      ░███████  ░██     ░██         ░██    \n░████   ░████ ░██    ░██ ░██      ░██   ░██  ░██   ░██   ░██   ░██     \n░███     ░███  ░███████  ░██      ░██    ░██  ░██████     ░██████      \n                                                                       \n                                                                       \n                                                                       \n   ░███                  ░██    ░██        ░██     ░██ ░██   ░██       \n  ░██░██                 ░██    ░██        ░██    ░██        ░██       \n ░██  ░██  ░██    ░██ ░████████ ░████████  ░██   ░██   ░██░████████    \n░█████████ ░██    ░██    ░██    ░██    ░██ ░███████    ░██   ░██       \n░██    ░██ ░██    ░██    ░██    ░██    ░██ ░██   ░██   ░██   ░██       \n░██    ░██ ░██   ░███    ░██    ░██    ░██ ░██    ░██  ░██   ░██       \n░██    ░██  ░█████░██     ░████ ░██    ░██ ░██     ░██ ░██    ░████    "
+  }
+}

packages/cli/src/lib/agent-interface.ts

@@ -4,13 +4,15 @@
  */
 
 import path from 'path';
-import clack from '../utils/clack';
-import { debug, logToFile, initLogFile, LOG_FILE_PATH } from '../utils/debug';
-import type { WizardOptions } from '../utils/types';
-import { analytics } from '../utils/analytics';
-import { WIZARD_INTERACTION_EVENT_NAME } from './constants';
-import { LINTING_TOOLS } from './safe-tools';
-import { getLlmGatewayUrlFromHost } from '../utils/urls';
+import { fileURLToPath } from 'url';
+import clack from '../utils/clack.js';
+import { debug, logToFile, initLogFile, LOG_FILE_PATH } from '../utils/debug.js';
+import type { WizardOptions } from '../utils/types.js';
+import { analytics } from '../utils/analytics.js';
+import { WIZARD_INTERACTION_EVENT_NAME } from './constants.js';
+import { LINTING_TOOLS } from './safe-tools.js';
+import { getLlmGatewayUrlFromHost } from '../utils/urls.js';
+import { getSettings } from './settings.js';
 
 // Dynamic import cache for ESM module
 let _sdkModule: any = null;
@@ -21,16 +23,6 @@ async function getSDKModule(): Promise<any> {
   return _sdkModule;
 }
 
-/**
- * Get the path to the bundled Claude Code CLI from the SDK package.
- * This ensures we use the SDK's bundled version rather than the user's installed Claude Code.
- */
-function getClaudeCodeExecutablePath(): string {
-  // require.resolve finds the package's main entry, then we get cli.js from same dir
-  const sdkPackagePath = require.resolve('@anthropic-ai/claude-agent-sdk');
-  return path.join(path.dirname(sdkPackagePath), 'cli.js');
-}
-
 // Using `any` because typed imports from ESM modules require import attributes
 // syntax which prettier cannot parse. See PR discussion for details.
 type SDKMessage = any;
@@ -254,9 +246,10 @@ export function initializeAgent(
     // Configure LLM gateway for Claude API calls
     // Local testing: use localhost LLM gateway
     // Production: use WorkOS production gateway
+    const settings = getSettings();
     const gatewayUrl = options.local
-      ? 'http://localhost:8000'
-      : getLlmGatewayUrlFromHost(config.workOSApiHost);
+      ? settings.gateway.development
+      : getLlmGatewayUrlFromHost();
 
     process.env.ANTHROPIC_BASE_URL = gatewayUrl;
     process.env.ANTHROPIC_AUTH_TOKEN = config.workOSApiKey;
@@ -279,7 +272,7 @@ export function initializeAgent(
           args: ['-y', '@workos/mcp-docs-server'],
         },
       },
-      model: 'claude-opus-4-5-20251101',
+      model: settings.model,
       allowedTools: [
         'Skill',
         'Read',
@@ -348,9 +341,7 @@ export async function runAgent(
 
   spinner.start(spinnerMessage);
 
-  const cliPath = getClaudeCodeExecutablePath();
   logToFile('Starting agent run');
-  logToFile('Claude Code executable:', cliPath);
   logToFile('Prompt:', prompt);
 
   const startTime = Date.now();
@@ -379,6 +370,8 @@ export async function runAgent(
 
     // Load plugin with bundled skills
     // Path from dist/src/lib/ back to package root
+    const __filename = fileURLToPath(import.meta.url);
+    const __dirname = path.dirname(__filename);
     const pluginPath = path.join(__dirname, '../../..');
     logToFile('Loading plugin from:', pluginPath);
 

packages/cli/src/lib/agent-runner.ts

@@ -2,32 +2,25 @@ import {
   getWelcomeMessage,
   SPINNER_MESSAGE,
   type FrameworkConfig,
-} from './framework-config';
-import type { WizardOptions } from '../utils/types';
+} from './framework-config.js';
+import type { WizardOptions } from '../utils/types.js';
 import {
-  abort,
   confirmContinueIfNoOrDirtyGitRepo,
   ensurePackageIsInstalled,
   getOrAskForWorkOSCredentials,
   getPackageDotJson,
   isUsingTypeScript,
   printWelcome,
-} from '../utils/clack-utils';
-import { analytics } from '../utils/analytics';
-import { WIZARD_INTERACTION_EVENT_NAME } from './constants';
-import clack from '../utils/clack';
-import {
-  initializeAgent,
-  runAgent,
-  AgentSignals,
-  AgentErrorType,
-} from './agent-interface';
-import { getCloudUrlFromRegion } from '../utils/urls';
+} from '../utils/clack-utils.js';
+import { analytics } from '../utils/analytics.js';
+import { WIZARD_INTERACTION_EVENT_NAME } from './constants.js';
+import clack from '../utils/clack.js';
+import { initializeAgent, runAgent } from './agent-interface.js';
 import chalk from 'chalk';
-import { uploadEnvironmentVariablesStep } from '../steps';
-import { autoConfigureWorkOSEnvironment } from './workos-management';
-import { detectPort, getCallbackPath } from './port-detection';
-import { writeEnvLocal } from './env-writer';
+import { uploadEnvironmentVariablesStep } from '../steps/index.js';
+import { autoConfigureWorkOSEnvironment } from './workos-management.js';
+import { detectPort, getCallbackPath } from './port-detection.js';
+import { writeEnvLocal } from './env-writer.js';
 
 /**
  * Universal agent-powered wizard runner.
@@ -134,7 +127,8 @@ export async function runAgentWizard(
     options,
   );
 
-  const agentResult = await runAgent(
+  // Run agent - errors will throw naturally with skill-based approach
+  await runAgent(
     agent,
     integrationPrompt,
     options,
@@ -146,9 +140,6 @@ export async function runAgentWizard(
     },
   );
 
-  // No error detection needed - we use skill-based approach
-  // If agent fails, it will error naturally
-
   // Build environment variables from WorkOS credentials
   const envVars = config.environment.getEnvVars(apiKey, clientId);
 

packages/cli/src/lib/api.ts

@@ -1,6 +1,6 @@
 import axios, { AxiosError } from 'axios';
 import { z } from 'zod';
-import { analytics } from '../utils/analytics';
+import { analytics } from '../utils/analytics.js';
 
 export const ApiUserSchema = z.object({
   distinct_id: z.string(),

packages/cli/src/lib/config.ts

@@ -1,7 +1,7 @@
-import { getPackageDotJson } from '../utils/clack-utils';
-import { hasPackageInstalled } from '../utils/package-json';
-import type { WizardOptions } from '../utils/types';
-import { Integration } from './constants';
+import { getPackageDotJson } from '../utils/clack-utils.js';
+import { hasPackageInstalled } from '../utils/package-json.js';
+import type { WizardOptions } from '../utils/types.js';
+import { Integration } from './constants.js';
 
 type IntegrationConfig = {
   name: string;

packages/cli/src/lib/constants.ts

@@ -1,3 +1,5 @@
+import { getSettings } from './settings.js';
+
 export enum Integration {
   nextjs = 'nextjs',
   react = 'react',
@@ -44,15 +46,12 @@ export const IS_DEV = ['test', 'development'].includes(
   process.env.NODE_ENV ?? '',
 );
 
-export const DEBUG = false;
-
-export const WORKOS_DOCS_URL = 'https://workos.com/docs/authkit';
-export const WORKOS_DASHBOARD_URL = 'https://dashboard.workos.com';
-export const ISSUES_URL = 'https://github.com/workos/authkit-wizard/issues';
-
-// Telemetry (disabled for now - can be enabled later)
-export const ANALYTICS_ENABLED = false;
-export const WIZARD_INTERACTION_EVENT_NAME = 'wizard interaction';
+const settings = getSettings();
 
-// OAuth port (kept for legacy compatibility, not used by WorkOS wizard)
-export const OAUTH_PORT = 8239;
+export const DEBUG = settings.logging.debugMode;
+export const WORKOS_DOCS_URL = settings.documentation.workosDocsUrl;
+export const WORKOS_DASHBOARD_URL = settings.documentation.dashboardUrl;
+export const ISSUES_URL = settings.documentation.issuesUrl;
+export const ANALYTICS_ENABLED = settings.telemetry.enabled;
+export const WIZARD_INTERACTION_EVENT_NAME = settings.telemetry.eventName;
+export const OAUTH_PORT = settings.legacy.oauthPort;

packages/cli/src/lib/env-writer.spec.ts

@@ -5,9 +5,9 @@ import {
   unlinkSync,
   writeFileSync,
   mkdtempSync,
-} from 'fs';
-import { join } from 'path';
-import { tmpdir } from 'os';
+} from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
 import { writeEnvLocal } from './env-writer.js';
 
 describe('writeEnvLocal', () => {

packages/cli/src/lib/framework-config.ts

@@ -1,5 +1,5 @@
-import type { Integration } from './constants';
-import type { WizardOptions } from '../utils/types';
+import type { Integration } from './constants.js';
+import type { WizardOptions } from '../utils/types.js';
 
 /**
  * Configuration interface for framework-specific agent integrations.