Reject invalid characters in quickstart

[miles-kt-inkeep]

No description provided.

[changeset-bot]

🦋 Changeset detected

Latest commit: 92d957c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 7 packages

Name	Type
@inkeep/agents-cli	Patch
@inkeep/agents-core	Patch
@inkeep/agents-manage-api	Patch
@inkeep/agents-manage-ui	Patch
@inkeep/agents-run-api	Patch
@inkeep/agents-sdk	Patch
@inkeep/create-agents	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
agents-manage-api	Ready	Preview	Comment	Oct 22, 2025 10:08pm
agents-manage-ui	Ready	Preview	Comment	Oct 22, 2025 10:08pm
agents-run-api	Ready	Preview	Comment	Oct 22, 2025 10:08pm

1 Skipped Deployment

Project	Deployment	Preview	Comments	Updated (UTC)
agents-docs	Skipped			Oct 22, 2025 10:08pm

[claude]

Claude finished @miles-kt-inkeep's task —— View job

---

TypeScript Staff Engineer Review

Review Checklist

• Read repository documentation and setup instructions
• Analyze the specific changes in utils.ts
• Research existing patterns and related code
• Evaluate security and validation approach
• Check for architectural consistency
• Assess customer impact and edge cases
• Provide comprehensive feedback and recommendations

---

Comprehensive Technical Review

Context & Changes

This PR introduces character validation for directory names in the createAgents function at packages/create-agents/src/utils.ts:114-116 and utils.ts:128-132. The validation restricts directory names to alphanumeric characters, hyphens, and underscores using the regex /^[a-zA-Z0-9_-]+$/.

✅ Positive Aspects

1. Consistency with Existing Patterns

• The validation regex /^[a-zA-Z0-9_-]+$/ perfectly matches the existing idSchema in /agents-manage-ui/src/lib/validation.ts:12, demonstrating good architectural consistency
• Both interactive prompt validation and programmatic input validation are handled, ensuring comprehensive coverage

2. Security & Robustness

• Prevents potential directory traversal attacks (../, ./)
• Blocks problematic characters that could cause issues across different file systems (Windows/Unix)
• Consistent error messaging between prompt and programmatic validation

⚠️ Areas for Improvement

1. DRY Principle Violation (Critical)

The regex /^[a-zA-Z0-9_-]+$/ and error message are duplicated across:

• Interactive validation function (lines 114-116)
• Programmatic validation (lines 128-132)
• Similar pattern exists in /agents-manage-ui/src/lib/validation.ts:12

Recommendation: Extract to a shared constant:

const DIRECTORY_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
const DIRECTORY_NAME_ERROR = 'Directory name can only contain letters, numbers, hyphens (-), and underscores (_)';

2. Missing Edge Cases (High)

The current validation doesn't handle several problematic scenarios:

Reserved Names: Windows reserves names like CON, PRN, AUX, NUL, COM1-9, LPT1-9

const RESERVED_NAMES = /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$/i;

Length Constraints: No minimum/maximum length validation (filesystem limits vary)

Leading/Trailing Issues: Names starting/ending with hyphens could cause issues

if (value.startsWith('-') || value.endsWith('-')) {
  return 'Directory name cannot start or end with hyphens';
}

3. Test Coverage Gap (High)

Examining /packages/create-agents/src/__tests__/utils.test.ts, there are no tests specifically covering the new character validation logic. This is concerning for a security-related feature.

Missing Test Cases:

• Invalid characters (spaces, @, #, etc.)
• Reserved Windows names
• Edge cases (empty string, very long names)
• Both interactive and programmatic validation paths

4. User Experience Considerations (Medium)

Error Message Clarity: The current message doesn't explain why these characters are restricted. Consider:

'Directory name can only contain letters, numbers, hyphens (-), and underscores (_) to ensure compatibility across all operating systems'

Suggestion Support: Could provide auto-sanitization suggestions:

const suggested = value.replace(/[^a-zA-Z0-9_-]/g, '-');
return `Invalid characters detected. Suggested: "${suggested}"`;

5. Architectural Concerns (Medium)

Cross-Package Validation: Similar directory/ID validation exists in agents-manage-ui. Consider creating a shared validation utility in agents-core to maintain consistency across packages.

Integration Points: This validation affects:

• File system operations (fs.mkdir, fs.pathExists)
• Git operations (if enabled)
• Template cloning paths
• Database project creation

All downstream effects should be considered for the validation rules.

Security Assessment

✅ Good: Prevents directory traversal
✅ Good: Blocks shell injection characters
⚠️ Missing: Reserved name protection
⚠️ Missing: Path length limits

Recommendations by Priority

High Priority:

1. Add comprehensive test coverage for all validation scenarios
2. Extract validation logic to shared constants/utilities
3. Add reserved name validation for Windows compatibility

Medium Priority:
4. Implement length constraints (1-255 characters)
5. Improve error messages with context
6. Consider creating shared validation utilities across packages

Low Priority:
7. Add auto-suggestion functionality for invalid names
8. Consider internationalization for error messages

Implementation Suggestions

// Shared validation utility
const DIRECTORY_VALIDATION = {
  pattern: /^[a-zA-Z0-9_-]+$/,
  reservedNames: /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$/i,
  minLength: 1,
  maxLength: 255,
  
  validate(value: string): string | undefined {
    if (!value || value.trim() === '') return 'Directory name is required';
    if (value.length < this.minLength || value.length > this.maxLength) {
      return `Directory name must be between ${this.minLength} and ${this.maxLength} characters`;
    }
    if (this.reservedNames.test(value)) {
      return 'Directory name cannot be a reserved system name';
    }
    if (!this.pattern.test(value)) {
      return 'Directory name can only contain letters, numbers, hyphens (-), and underscores (_)';
    }
    return undefined;
  }
};

Conclusion

While this PR addresses an important security concern and follows existing patterns well, it needs enhanced test coverage, better edge case handling, and consolidation of validation logic to meet production standards. The core approach is sound but requires refinement for robustness.

---