Auto-generate Dockerfile during deployment if requirements are met

[MichaelSchmidle]

Problem

Currently, users must explicitly run light generate dockerfile after adding required scripts to package.json. This creates friction in the deployment workflow:

1. User runs light up production (configures environment interactively)
2. Error: "Dockerfile not found"
3. User adds build and start scripts to package.json
4. User runs light generate dockerfile
5. User runs light up production again

This is 3 extra steps after the initial error.

Proposed Solution

Smart auto-generation in light up <env> (deployment mode):

1. Check if Dockerfile exists → if yes, proceed
2. Check if package.json has required scripts → if no, show error (current behavior)
3. If scripts exist but Dockerfile missing → auto-generate and continue

Example Flow (Improved)

# User runs deployment for first time
light up production

# CLI detects valid scripts, generates Dockerfile automatically
ℹ Dockerfile not found, but package.json has required scripts
✓ Generated Dockerfile automatically
ℹ Review and customize: Dockerfile
✓ Building app container...

Implementation Details

In up.ts (deployment mode validation):

// FR-012 Auto-generation: Generate Dockerfile if scripts are valid
if (!existsSync('Dockerfile')) {
  // Check if package.json has required scripts
  if (existsSync('package.json')) {
    const packageJson = JSON.parse(readFileSync('package.json', 'utf-8'));
    const scripts = packageJson.scripts || {};

    if (scripts.build && scripts.start) {
      // Scripts exist - auto-generate Dockerfile
      console.log(chalk.blue('ℹ'), 'Dockerfile not found, but package.json has required scripts');
      
      const dockerfile = generateDockerfile({
        nodeVersion: '20-alpine',
        packageManager: 'npm',
        buildCommand: 'build',
        startCommand: 'start',
        appPort: 3000
      });
      
      writeFileSync('Dockerfile', dockerfile);
      console.log(chalk.green('✓'), 'Generated Dockerfile automatically');
      console.log(chalk.blue('ℹ'), 'Review and customize:', chalk.cyan('Dockerfile'));
      console.log();
      
      // Continue with deployment (Dockerfile now exists)
    } else {
      // Scripts missing - show current error message
      throw new Error(...);
    }
  }
}

Benefits

1. Reduced friction: Users don't need to learn light generate dockerfile command
2. Progressive disclosure: Dockerfile appears exactly when needed
3. Transparency: Clear message that it was auto-generated
4. Escape hatch: Users can still customize Dockerfile before re-running
5. Safe: Only generates if scripts are valid (no blind generation)

Success Criteria

• User runs light up <env> for first time → Dockerfile auto-generated if scripts valid
• Clear console output showing auto-generation happened
• Existing light generate dockerfile command still works (for manual regeneration)
• Error message still shows if scripts are missing (same as now)
• No behavior change if Dockerfile already exists

Related

• Spec 002 (FR-012): Introduced silent skip during init
• light generate dockerfile: Current manual workaround
• Issue Dev server host binding and SSL certificate trust #18: Dev server configuration (similar progressive disclosure pattern)

Notes

This is the proper fix for the workflow introduced in Spec 002. The current light generate dockerfile command was added as a bridge solution to unblock deployment testing.

[MichaelSchmidle]

Closing as wont-fix based on architectural decision during Spec 002 implementation.

Decision

Lightstack CLI will NOT generate Dockerfiles - this violates Constitutional Principle #1: "Don't Reinvent the Wheel."

Rationale

Dockerfile generation is a complex problem already solved by battle-tested tools:

• Docker Init (recommended): Interactive CLI that generates optimized Dockerfiles for detected frameworks
• Nixpacks (Railway): Auto-detects and builds apps without Dockerfiles
• Paketo Buildpacks: Cloud Native buildpacks for production workloads

Supporting all frameworks, package managers, workspace configurations, and build patterns would:

1. Create significant maintenance burden
2. Still not match specialized tools
3. Violate the "orchestrate, don't reinvent" principle

New Approach (Updated FR-012)

During light init:

• Check if Dockerfile exists
• If missing, show informative message: "For deployment mode, you'll need a Dockerfile. Create one with: docker init (recommended)"

During light up <env> (deployment):

• Validate Dockerfile exists
• If missing, show error with clear guidance:

  Dockerfile required for deployment mode.
  
  Create one using:
    • docker init (recommended - interactive setup)
    • Manual creation (see docs)
  
  Alternatively, use development mode: light up
  

Impact

• ✅ Better: Users get battle-tested Dockerfiles from docker init
• ✅ Simpler: CLI has less code to maintain
• ✅ Clearer: Single responsibility - orchestrate existing tools
• ⚠️ Trade-off: One extra step (docker init) before deployment

Related Changes

• Updated Spec 002 Clarifications (Session 2025-10-12)
• Removed light generate dockerfile command
• Removed generateDockerfile() utility
• Updated error messages to point to docker init

Spec 002 will be updated accordingly.