Skip to content

Commit ff59c19

Browse files
fmontesclaudeCopilot
authored
fix(create-app): Fix critical CLI validation bugs and improve error handling (#34472)
## Summary Fixes critical bugs and adds robust validation to the `@dotcms/create-app` CLI tool. This PR addresses multiple issues including nested directory creation, path display problems, exit code inconsistencies, authentication failures, and improves overall error handling with comprehensive pre-flight checks. --- ## Key Improvements & Bug Fixes ### 🐛 Critical Bug Fixes #### 1. **Nested Directory Structure** (NEW) **Issue:** Running CLI with directory path that includes project name created nested structure ```bash # Before dotcms-create-app my-app -d /tmp/my-app # Created: /tmp/my-app/my-app ❌ # After # Creates: /tmp/my-app ✅ ``` **Fix:** Detect when directory path already ends with project name and avoid double-nesting #### 2. **Directory Path Display** (NEW) **Issue:** Confusing output with excessive parent directory traversals ```bash # Before cd ../../../../tmp/test-dir/my-project # After cd /tmp/test-dir/my-project # Cleaner absolute path ``` **Fix:** Smart path display logic - uses absolute paths when relative would have 3+ parent traversals #### 3. **Exit Code Consistency** (NEW) **Issue:** CLI exited with code 0 on failures, breaking CI/CD detection ```bash # 14+ failure scenarios were exiting with code 0 ``` **Fix:** All error paths now use `process.exit(1)` for proper failure signaling #### 4. **Authentication Error Handling** (NEW) **Issue:** Cryptic JSON dumps on wrong credentials, no retry mechanism ```bash # Before: JSON error dump # After: Clear message with 3-attempt retry ``` **Fix:** - User-friendly error messages distinguishing 401 vs connection vs server errors - 3-attempt retry loop for authentication failures - Users can correct credentials without restarting CLI #### 5. **URL Trailing Slash Issues** (NEW) **Issue:** URLs with trailing slashes caused double-slash API endpoints ```bash https://demo.dotcms.com/ + /api/v1/... → https://demo.dotcms.com//api/v1/... ``` **Fix:** Normalize URLs by stripping trailing slashes before API calls ### 🐳 Docker & Port Pre-Flight Checks **Before:** Generic error ``` ✖ Failed to start dotCMS ensure docker is running and ports 8082, 8443, 9200, and 9600 are free. ``` **After:** Specific errors with solutions - ✅ Check Docker availability → Installation instructions + download link - ✅ Check port conflicts → Lists busy ports with platform-specific diagnostic commands (`lsof` / `netstat`) - ✅ Container diagnostics → Shows status and logs when startup fails ### 🛡️ Input Validation - **Project names:** Stricter validation - only alphanumeric, hyphens, underscores, dots (no path traversal, reserved names) - **Frameworks:** Supports aliases (`next` → `nextjs`) and case-insensitive matching - **URLs:** Protocol requirement (`https://` or `http://`), trailing slash normalization - **Usernames/Passwords:** Non-empty field validation - **Parameters:** Warns when mixing `--local` with cloud flags (`--url`, `-u`, `-p`) ### 🔧 Error Handling & Code Quality - Added health check retry constants (Cloud: 5 attempts, Local: 60 attempts) - Better variable naming (`healthCheckResult` vs `checkIfDotcmsIsRunning`) - Changed `console.log` → `console.error` for error outputs (proper stream) - Fixed typos throughout codebase - Added comprehensive JSDoc comments - Modular utility organization (`getDockerDiagnostics()` moved to utils) ### 🔒 Security - Path traversal prevention in project names - Shell injection protection with `escapeShellPath()` utility - URL protocol validation (prevents file:// or javascript: schemes) - Cross-platform command escaping (Windows/macOS/Linux) --- ## Detailed Changes by Category ### Authentication & Network (4 commits) - ✅ Enhanced `getAuthToken()` API error handling - ✅ 3-attempt authentication retry with user prompts - ✅ URL trailing slash normalization - ✅ Distinguish 401 vs connection vs 500 errors ### Validation (2 commits) - ✅ Stricter project name validation (alphanumeric + `-_.` only) - ✅ URL validation with protocol requirement - ✅ Empty field validation for credentials - ✅ Conflicting parameter detection ### Directory Handling (2 commits) - ✅ Prevent nested directory structures - ✅ Smart relative/absolute path display ### Infrastructure (3 commits) - ✅ Docker availability checks with actionable errors - ✅ Port conflict detection (8082, 8443, 9200, 9600) - ✅ Container diagnostic utilities - ✅ Exit code consistency (`process.exit(1)` on all failures) --- ## Files Changed | File | Changes | Description | |------|---------|-------------| | `src/index.ts` | +60/-30 | Main CLI flow, authentication retry, path display | | `src/utils/index.ts` | +140/-10 | Docker checks, port validation, path helpers | | `src/utils/validation.ts` | +318 (new) | Comprehensive input validation | | `src/asks.ts` | +30/-10 | Directory preparation, nested structure fix | | `src/api/index.ts` | +20/-5 | Enhanced error handling | | `src/constants/index.ts` | +5 | Health check retry constants | **Total:** ~500 lines added/modified across 7 commits --- ## Testing ✅ Build passing (`nx run sdk-create-app:build`) ✅ Lint passing (`nx run sdk-create-app:lint`) ✅ All pre-commit hooks passing ✅ Manually tested: Docker checks, port conflicts, auth retries, path display, nested directories ### Test Scenarios Validated - ✅ Wrong credentials → retry 3 times with friendly messages - ✅ Docker not running → clear installation instructions - ✅ Ports busy → lists conflicts with diagnostic commands - ✅ Directory path includes project name → no nesting - ✅ Deep relative paths → shows absolute when cleaner - ✅ All failures → exit with code 1 (not 0) - ✅ URL trailing slashes → normalized correctly - ✅ Invalid project names → clear validation errors --- ## Breaking Changes None - all changes are additive and backward compatible. --- ## Related Issues Fixes multiple critical bugs discovered during QA testing of `@dotcms/create-app` CLI tool. --------- Co-authored-by: Claude Sonnet 4.5 (1M context) <noreply@anthropic.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent 4b78768 commit ff59c19

7 files changed

Lines changed: 1204 additions & 192 deletions

File tree

‎core-web/libs/sdk/create-app/README.md‎

Lines changed: 156 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,12 @@
33
> 🚧 **Beta Notice:**
44
> This CLI is currently in **beta**. Features and APIs may change as we continue improving the tool.
55
6-
With a single command, you can bootstrap a fully functional frontend (Next.js,Vue,Angular, etc.) connected to dotCMS APIs — including the following:
6+
With a single command, you can bootstrap a fully functional frontend (Next.js, Angular, Astro, etc.) connected to dotCMS APIs — including the following:
77

8-
- Spinning up dotCMS using docker
9-
- Universal Visual Editor pre configured
10-
- Generating site id and authentication token (just copy paste them in frontend .env and enjoy).
8+
- Spinning up dotCMS using Docker with intelligent pre-flight checks
9+
- Universal Visual Editor pre-configured
10+
- Generating site ID and authentication token (just copy paste them in frontend .env and enjoy)
11+
- Comprehensive validation and helpful error messages
1112

1213
---
1314

@@ -17,12 +18,13 @@ With a single command, you can bootstrap a fully functional frontend (Next.js,Vu
1718

1819
It automates the tedious work of:
1920

20-
- Setting up a framework
21+
- Setting up a framework with best practices
2122
- Connecting to dotCMS REST & GraphQL APIs
2223
- Providing content-fetching helpers
2324
- Adding example components & pages
2425
- Creating environment variable templates
25-
- Optional Setting up local dotCMS instance using docker.
26+
- Optionally setting up local dotCMS instance using Docker
27+
- Validating your environment (Docker, ports, URLs)
2628

2729
This tool lets you focus on **building**, not configuring.
2830

@@ -65,8 +67,12 @@ npx @dotcms/create-app <project-name>
6567
This will:
6668

6769
- Ask for the target directory
68-
- Ask which frontend framework you want (Next.js,Angular,Vue, etc.)
69-
- Ask if you’re using dotCMS Cloud or Local Docker dotCMS
70+
- Ask which frontend framework you want (Next.js, Angular, Astro, etc.)
71+
- Ask if you're using dotCMS Cloud or Local Docker dotCMS
72+
- **For local Docker setup:**
73+
- Check if Docker is installed and running
74+
- Verify required ports are available (8082, 8443, 9200, 9600)
75+
- Provide specific error messages and solutions if issues are found
7076
- Automatically scaffold your project
7177
- Configure UVE (Edit Mode Anywhere)
7278
- Start dotCMS (if using Docker)
@@ -88,12 +94,145 @@ API Token : YOUR_API_TOKEN
8894
create-dotcms-app <project-name> [options]
8995
```
9096

91-
| Option | Description |
92-
|--------------------------|-----------------------------------------------------------------------------------------------------------------|
93-
| `-f, --framework <name>` | Skip prompts and directly choose a framework. Must be one of: `nextjs`, `angular`, `angular-ssr`, `astro`, etc. |
94-
| `-d, --directory` | Project Directory |
95-
| `--local` | Use local dotCMS instance using docker: |
96-
| `-u, --username` | dotCMS instance username (skip in case of local) |
97-
| `-p, --password` | dotCMS instance password (skip in case of local)
98-
| `--url` | dotCMS instance url (skip in case of local) |
99-
| `-V, --version` | Show CLI version |
97+
| Option | Description |
98+
|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
99+
| `-f, --framework <name>` | Skip prompts and directly choose a framework. Supported: `nextjs`, `angular`, `angular-ssr`, `astro`. Case-insensitive. Aliases: `next`, `ng`, `next.js`, `angular-server` |
100+
| `-d, --directory` | Project Directory |
101+
| `--local` | Use local dotCMS instance using docker |
102+
| `-u, --username` | dotCMS instance username (skip in case of local) |
103+
| `-p, --password` | dotCMS instance password (skip in case of local) |
104+
| `--url` | dotCMS instance URL (skip in case of local). Must include protocol (http:// or https://) |
105+
| `-V, --version` | Show CLI version |
106+
107+
### Framework Aliases
108+
109+
For convenience, the CLI accepts common framework name variations (case-insensitive):
110+
111+
- `next`, `next.js`, `Next.js` → `nextjs`
112+
- `ng`, `Angular` → `angular`
113+
- `angular-server` → `angular-ssr`
114+
- `angular-server` → `angular-ssr`
115+
116+
### URL Format
117+
118+
When using `--url`, make sure to include the full URL with protocol:
119+
120+
✅ **Valid:** `https://demo.dotcms.com`, `http://localhost:8082`
121+
❌ **Invalid:** `demo.dotcms.com`, `localhost:8082` (missing protocol)
122+
123+
---
124+
125+
## 🛡️ Built-in Validation & Error Handling
126+
127+
The CLI includes comprehensive validation to help you avoid common setup issues:
128+
129+
### Input Validation
130+
- **Project names:** Validates against filesystem limitations, reserved names, special characters, and path traversal
131+
- **Framework names:** Supports aliases and case-insensitive matching
132+
- **URLs:** Ensures proper protocol and format
133+
- **Conflicting parameters:** Warns when mixing `--local` with cloud parameters
134+
135+
### Docker Environment Checks
136+
When using local Docker setup, the CLI performs pre-flight checks:
137+
138+
1. **Docker Availability**
139+
- Verifies Docker is installed and running
140+
- Provides installation instructions if not found
141+
- Direct link to Docker Desktop download
142+
143+
2. **Port Availability**
144+
- Checks all required ports before starting containers
145+
- Lists which specific ports are busy
146+
- Provides platform-specific commands to identify blocking processes
147+
- Suggests `docker compose down` to stop existing containers
148+
149+
3. **Container Health**
150+
- Monitors dotCMS startup with intelligent retries
151+
- Shows detailed diagnostics if startup fails
152+
- Displays container status and recent logs
153+
154+
### Error Messages
155+
All error messages include:
156+
- **Clear problem description** - What went wrong
157+
- **Specific suggestions** - How to fix it
158+
- **Alternative solutions** - Other ways to proceed
159+
- **Platform-specific commands** - Commands tailored to your OS
160+
161+
### Debug Mode
162+
Run with `DEBUG=1` to see detailed stack traces:
163+
```sh
164+
DEBUG=1 npx @dotcms/create-app my-project
165+
```
166+
167+
---
168+
169+
## 🔧 Troubleshooting
170+
171+
### Docker Issues
172+
173+
**"Docker is not available"**
174+
- Ensure Docker Desktop is installed and running
175+
- Check the Docker icon in your system tray
176+
- Download from: https://www.docker.com/products/docker-desktop
177+
178+
**"Required ports are already in use"**
179+
- Check what's using the ports:
180+
- macOS/Linux: `lsof -i :8082`
181+
- Windows: `netstat -ano | findstr ":8082"`
182+
- Stop existing dotCMS containers: `docker compose down`
183+
- Stop conflicting services or choose a different port mapping
184+
185+
**"dotCMS failed to start properly"**
186+
- Check container logs: `docker logs <container-name>`
187+
- Verify sufficient system resources (RAM, disk space)
188+
- Review Docker diagnostics output from the CLI
189+
190+
### Validation Errors
191+
192+
**"Invalid project name"**
193+
- Avoid special characters: `< > : " | ? *`
194+
- Don't use Windows reserved names: `CON`, `PRN`, `AUX`, `NUL`, etc.
195+
- Maximum 255 characters
196+
- No path traversal patterns (`..`)
197+
198+
**"Invalid URL format"**
199+
- Include protocol: `https://` or `http://`
200+
- Verify hostname is correct
201+
- For localhost, default port is 8082
202+
203+
---
204+
205+
## 🚀 Examples
206+
207+
### Quick Start with Interactive Prompts
208+
```sh
209+
npx @dotcms/create-app my-blog
210+
```
211+
212+
### Using CLI Flags (Skip Prompts)
213+
```sh
214+
# Local Docker setup
215+
npx @dotcms/create-app my-blog --framework nextjs --local
216+
217+
# Cloud instance
218+
npx @dotcms/create-app my-blog \
219+
--framework angular \
220+
--url https://demo.dotcms.com \
221+
--username admin@dotcms.com \
222+
--password mypassword
223+
```
224+
225+
### Debug Mode
226+
```sh
227+
DEBUG=1 npx @dotcms/create-app my-blog --framework nextjs --local
228+
```
229+
230+
---
231+
232+
## 🔒 Security Notes
233+
234+
- Never commit API tokens or passwords to version control
235+
- The CLI validates all inputs to prevent injection attacks
236+
- Project names are sanitized to prevent path traversal
237+
- Shell commands are properly escaped for cross-platform safety
238+

‎core-web/libs/sdk/create-app/src/api/index.ts‎

Lines changed: 37 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,9 @@
11
import axios from 'axios';
2+
import chalk from 'chalk';
23
import { Ok, type Result, Err } from 'ts-results';
34

45
import { DOTCMS_DEMO_SITE, DOTCMS_EMA_CONFIG_API, DOTCMS_TOKEN_API } from '../constants';
5-
import {
6-
FailedToGetDemoSiteIdentifierError,
7-
FailedToGetDotcmsTokenError,
8-
FailedToSetUpUVEConfig
9-
} from '../errors';
6+
import { FailedToGetDemoSiteIdentifierError, FailedToSetUpUVEConfig } from '../errors';
107

118
import type {
129
DemoSiteResponse,
@@ -27,14 +24,45 @@ export class DotCMSApi {
2724
}: {
2825
payload: GetUserTokenRequest;
2926
url?: string;
30-
}): Promise<Result<string, FailedToGetDotcmsTokenError>> {
27+
}): Promise<Result<string, string>> {
28+
const endpoint = url || this.defaultTokenApi;
29+
3130
try {
32-
const endpoint = url || this.defaultTokenApi;
3331
const res = await axios.post<GetUserTokenResponse>(endpoint, payload);
3432
return Ok(res.data.entity.token);
3533
} catch (err) {
36-
console.error('dotCMS failed to get token' + JSON.stringify(err));
37-
return Err(new FailedToGetDotcmsTokenError());
34+
// Provide specific error messages based on error type
35+
if (axios.isAxiosError(err)) {
36+
if (err.response?.status === 401) {
37+
return Err(
38+
chalk.red('\n❌ Authentication failed\n\n') +
39+
chalk.white('Invalid username or password.\n\n') +
40+
chalk.yellow('Please check your credentials and try again:\n') +
41+
chalk.white(' • Verify your username is correct\n') +
42+
chalk.white(' • Ensure your password is correct\n') +
43+
chalk.white(' • Check if your account is active\n')
44+
);
45+
} else if (err.code === 'ECONNREFUSED') {
46+
return Err(
47+
chalk.red('\n❌ Connection refused\n\n') +
48+
chalk.white(`Could not connect to dotCMS at: ${endpoint}\n\n`) +
49+
chalk.yellow('Please verify:\n') +
50+
chalk.white(' • The URL is correct\n') +
51+
chalk.white(' • The dotCMS instance is running\n') +
52+
chalk.white(' • There are no firewall issues\n')
53+
);
54+
} else if (err.response) {
55+
return Err(
56+
chalk.red(`\n❌ Server error (${err.response.status})\n\n`) +
57+
chalk.white('The dotCMS server returned an error.\n') +
58+
chalk.gray(`Details: ${err.response.statusText || 'Unknown error'}\n`)
59+
);
60+
}
61+
}
62+
return Err(
63+
chalk.red('\n❌ Failed to get authentication token\n\n') +
64+
chalk.gray(err instanceof Error ? err.message : String(err))
65+
);
3866
}
3967
}
4068

‎core-web/libs/sdk/create-app/src/asks.ts‎

Lines changed: 54 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import inquirer from 'inquirer';
44
import path from 'path';
55

66
import { FRAMEWORKS_CHOICES } from './constants';
7+
import { validateProjectName, validateUrl } from './utils/validation';
78

89
import type { SupportedFrontEndFrameworks } from './types';
910

@@ -32,7 +33,15 @@ export async function askProjectName() {
3233
type: 'input',
3334
name: 'projectName',
3435
message: 'What is your project name ?',
35-
default: `my-dotcms-app`
36+
default: `my-dotcms-app`,
37+
validate: (input: string) => {
38+
try {
39+
validateProjectName(input);
40+
return true;
41+
} catch (error) {
42+
return error instanceof Error ? error.message : String(error);
43+
}
44+
}
3645
}
3746
]);
3847
return ans.projectName;
@@ -62,7 +71,15 @@ export async function askDotcmsCloudUrl() {
6271
type: 'input',
6372
name: 'url',
6473
message: 'dotCMS instance URL:',
65-
default: `https://demo.dotcms.com`
74+
default: `https://demo.dotcms.com`,
75+
validate: (input: string) => {
76+
try {
77+
validateUrl(input);
78+
return true;
79+
} catch (error) {
80+
return error instanceof Error ? error.message : String(error);
81+
}
82+
}
6683
}
6784
]);
6885
return ans.url;
@@ -77,14 +94,20 @@ export async function askUserNameForDotcmsCloud() {
7794
type: 'input',
7895
name: 'username',
7996
message: 'Username:',
80-
default: `admin@dotcms.com`
97+
default: `admin@dotcms.com`,
98+
validate: (input: string) => {
99+
if (!input || input.trim() === '') {
100+
return 'Username cannot be empty';
101+
}
102+
return true;
103+
}
81104
}
82105
]);
83106
return ans.username;
84107
}
85108

86109
/**
87-
* Ask user the ulsername of the dotCMS instance
110+
* Ask user the password of the dotCMS instance
88111
*/
89112
export async function askPasswordForDotcmsCloud() {
90113
const ans = await inquirer.prompt([
@@ -93,7 +116,13 @@ export async function askPasswordForDotcmsCloud() {
93116
name: 'password',
94117
mask: '•',
95118
message: 'Password:',
96-
default: `admin`
119+
default: `admin`,
120+
validate: (input: string) => {
121+
if (!input || input.trim() === '') {
122+
return 'Password cannot be empty';
123+
}
124+
return true;
125+
}
97126
}
98127
]);
99128
return ans.password;
@@ -124,7 +153,7 @@ export async function askCloudOrLocalInstance(): Promise<boolean> {
124153
{
125154
type: 'select',
126155
name: 'isCloud',
127-
message: 'Do you have an exsisting dotCMS instance?',
156+
message: 'Do you have an existing dotCMS instance?',
128157
choices: [
129158
{ name: 'Yes - I have a dotCMS instance URL', value: true },
130159
{ name: 'No - Spin up dotCMS locally with Docker', value: false }
@@ -142,9 +171,27 @@ export async function askCloudOrLocalInstance(): Promise<boolean> {
142171
* user enters: "."
143172
* projectName: "my-app"
144173
* final path becomes "./my-app"
174+
*
175+
* @remarks
176+
* - Prevents nested directories when basePath already ends with projectName
177+
* - Example: basePath="/tmp/my-app" + projectName="my-app" → "/tmp/my-app" (not "/tmp/my-app/my-app")
178+
* - Handles both absolute and relative paths correctly
145179
*/
146180
export async function prepareDirectory(basePath: string, projectName: string) {
147-
const targetPath = path.resolve(basePath, projectName);
181+
// Resolve basePath to absolute path for consistent comparison
182+
const resolvedBasePath = path.resolve(basePath);
183+
const basePathDirName = path.basename(resolvedBasePath);
184+
185+
// Check if basePath already ends with the project name
186+
// This prevents nested directories like "/tmp/my-app/my-app"
187+
let targetPath: string;
188+
if (basePathDirName === projectName) {
189+
// User specified full path including project name (e.g., "-d /tmp/my-app" with projectName="my-app")
190+
targetPath = resolvedBasePath;
191+
} else {
192+
// User specified parent directory (e.g., "-d /tmp" with projectName="my-app")
193+
targetPath = path.resolve(resolvedBasePath, projectName);
194+
}
148195

149196
// If path doesn't exist → create
150197
if (!fs.existsSync(targetPath)) {

0 commit comments

Comments
 (0)