PLAN.md

TODO - devenvmgr/interpreters

Generated: 2026-02-03
Analysis Date: 2026-02-03

---

Critical Issues (Will Break Functionality)

1. Poetry Not Installed ❌ HIGH PRIORITY

Impact: Poetry commands will fail despite documentation claiming support

Problem:

• Dockerfile line 79: Claims poetry in package managers label
• Dockerfile line 41: ARG POETRY_VERSION=1.8.4 defined but never used
• Dockerfile lines 326-364: pip3 installs pipenv, pdm, hatch but NO poetry
• Entrypoint lines 162-164, 463-464: Tries to use poetry install

Fix:

# Add after line 364 in Dockerfile
RUN pip3 install --no-cache-dir --break-system-packages poetry==${POETRY_VERSION}

Files to modify:

• Dockerfile (add poetry installation)
• Verify docker/entrypoint.sh poetry commands work after fix

---

2. versions.env Not Used ❌ HIGH PRIORITY

Impact: Violates DRY principle, maintenance nightmare with duplicate version definitions

Problem:

• versions.env exists with 130 lines of version definitions
• Dockerfile never sources or uses these variables
• Versions are hardcoded in both files

Fix: Two options:

1. Remove versions.env if not needed
2. Source it in Dockerfile: ARG BUN_VERSION should read from versions.env

Recommended: Use versions.env with build-time variable substitution

Files to modify:

• Dockerfile (source and use versions.env)
• Makefile (pass env vars to docker build)
• Consider adding scripts/load-versions.sh

---

Security Issues ⚠️

3. Running as Root

Impact: Security best practice violation, container runs with elevated privileges

Problem:

• No USER, useradd, or adduser commands in Dockerfile
• Everything runs as root user
• Modern container best practice is to use non-root user

Fix:

# Add before WORKDIR /workspace
RUN addgroup -g 1000 devenv && \
    adduser -D -u 1000 -G devenv devenv && \
    chown -R devenv:devenv /workspace /opt /usr/local/bundle

USER devenv

Considerations:

• Some package managers expect specific permissions
• May need to adjust GEM_HOME, COMPOSER_HOME paths
• Test all runtimes after switching to non-root

Files to modify:

• Dockerfile
• .devcontainer/devcontainer.json (update remoteUser to "devenv")

---

4. No SHA256 Verification

Impact: Supply chain security risk, no integrity verification for downloaded binaries

Problem:

• Binary downloads (Bun, Deno, Hugo, Julia, Zola, Groovy) have no checksum validation
• versions.env has placeholder SHA256=placeholder values

Fix:

# Example for Bun
RUN set -ex && \
    if [ "$(uname -m)" = "x86_64" ]; then \
        wget -q "https://github.com/oven-sh/bun/releases/download/bun-v${BUN_VERSION}/bun-linux-x64.zip" && \
        echo "${BUN_SHA256}  bun-linux-x64.zip" | sha256sum -c - && \
        unzip -q bun-linux-x64.zip && \
        ...

Files to modify:

• versions.env (replace all placeholder SHA256 values with real checksums)
• Dockerfile (add sha256sum verification for all binary downloads)
• Consider adding scripts/update-checksums.sh automation

---

5. No HEALTHCHECK

Impact: Cannot monitor container health, orchestrators can't detect failures

Fix:

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD node --version && python3 --version || exit 1

Files to modify:

• Dockerfile

---

Incomplete Features 📋

6. Groovy Installed But Not Integrated

Impact: Dead code, wasted image space (~100MB)

Problem:

• Groovy 4.0 installed (lines 271-278 in Dockerfile)
• No project detection in entrypoint.sh (no check for build.gradle, settings.gradle)
• No install/dev/build automation for Groovy projects

Options:

1. Complete the integration (add Groovy detection to entrypoint)
2. Remove Groovy if not needed

Fix (Option 1 - Complete integration): Add to docker/entrypoint.sh around line 357:

# =========================================================================
# Groovy (Gradle projects)
# =========================================================================
if [ -z "$detected" ]; then
    if [ -f "$dir/build.gradle" ] || [ -f "$dir/build.gradle.kts" ] || [ -f "$dir/settings.gradle" ]; then
        detected="groovy"
        runtime="groovy"
        package_manager="gradle"
        framework="Groovy/Gradle"
        print_success "Detected: Groovy/Gradle project"
    fi
fi

Add install/build commands around lines 505, 689

Files to modify:

• docker/entrypoint.sh (add Groovy/Gradle detection and commands)

---

7. Zola Installed But Not in Auto-Detect

Impact: Users can't use auto-detect features for Zola projects

Problem:

• Zola binary installed (lines 255-269 in Dockerfile)
• Not integrated into entrypoint.sh auto-detection
• No --install, --dev, --build support

Fix: Add to docker/entrypoint.sh around line 367:

# =========================================================================
# Zola (static site generator)
# =========================================================================
if [ -z "$detected" ] && [ -f "$dir/config.toml" ] && grep -q '\[extra\]' "$dir/config.toml" 2>/dev/null; then
    detected="zola"
    runtime="zola"
    package_manager="zola"
    framework="Zola"
    print_success "Detected: Zola static site"
fi

Add dev/build commands around lines 611, 695

Files to modify:

• docker/entrypoint.sh

---

8. Empty scripts/ Directory

Impact: Confusing, triggers CI unnecessarily

Problem:

• scripts/ directory exists but is completely empty
• Referenced in CI/CD workflow (line 13 of .github/workflows/build.yml)
• Unclear purpose

Options:

1. Remove directory and CI reference
2. Add utility scripts (update-versions.sh, test-project.sh, etc.)

Recommended: Add utility scripts

Suggested scripts:

• scripts/update-checksums.sh - Fetch and update SHA256 checksums
• scripts/test-all-runtimes.sh - Local testing script
• scripts/scaffold-project.sh - Create test projects for each framework

Files to modify:

• Add scripts to scripts/ directory
• Or remove references in .github/workflows/build.yml

---

Missing Features (Enhancements)

9. No Test Projects in Repository

Impact: CI only tests version commands, not actual project builds

Recommendation: Create tests/ directory with sample projects:

• tests/nextjs/ - Minimal Next.js project
• tests/django/ - Minimal Django project
• tests/jekyll/ - Minimal Jekyll site
• tests/hugo/ - Minimal Hugo site
• etc.

Update CI to build these projects as integration tests.

---

10. Missing Documentation Files

Needed:

• CHANGELOG.md - Track version changes
• SECURITY.md - Security policy and vulnerability reporting
• CONTRIBUTING.md - Contribution guidelines
• CODE_OF_CONDUCT.md - Community guidelines

---

11. No Security Scanning in CI

Recommendation: Add to .github/workflows/build.yml:

- name: Run Trivy vulnerability scanner
  uses: aquasecurity/trivy-action@master
  with:
    image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
    format: 'sarif'
    output: 'trivy-results.sarif'

- name: Upload Trivy results to GitHub Security
  uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: 'trivy-results.sarif'

---

12. Image Size Not Tracked

Recommendation:

• Add image size reporting to CI summary
• Track size over time
• Set up alerts if image grows significantly

---

13. Missing --test Command

Recommendation: Add --test flag to entrypoint.sh that validates:

• All runtimes are working
• All package managers are functional
• Network connectivity
• Write permissions

---

14. No docker-compose Examples

Recommendation: Add examples/ directory with:

• examples/docker-compose.nextjs.yml
• examples/docker-compose.django.yml
• examples/docker-compose.jekyll.yml

---

Minor Issues

15. Poetry Version Check Missing

• Entrypoint line 409 shows Poetry version but Poetry isn't installed
• Will show empty output

16. Hexo Detection Could Be Enhanced

• Only detects if Ghost is present
• Should detect hexo independently

17. Docusaurus Detection Incomplete

• Installed globally but detection relies on package.json grep
• Could be more robust

---

Priority Matrix

Fix Immediately (P0):

1. ✅ Install Poetry
2. ✅ Fix or remove versions.env

Fix Soon (P1):

3. ✅ Add non-root user
4. ✅ Complete Groovy integration OR remove it
5. ✅ Complete Zola integration

Nice to Have (P2):

6. ✅ Add SHA256 verification
7. ✅ Add HEALTHCHECK
8. ✅ Add test projects
9. ✅ Add security scanning
10. ✅ Clean up scripts/ directory

Future Enhancements (P3):

11. ✅ Add documentation files
12. ✅ Add --test command
13. ✅ Add docker-compose examples
14. ✅ Image size tracking

---

Notes

• All line numbers reference current file versions as of 2026-02-03
• Test thoroughly after each fix
• Consider multi-stage builds to reduce final image size
• Consider adding language version managers (nvm, pyenv, rbenv) for flexibility