Skip to content

CLAUDE.md

Latest commit

 

History

History
104 lines (79 loc) · 3.67 KB

CLAUDE.md

File metadata and controls

104 lines (79 loc) · 3.67 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This repository provides a Dev Container Feature that installs Jetify Devbox in development containers. Devbox is a command-line tool that creates isolated shells for development using Nix.

Key Commands

Testing

# Run all tests
devcontainer features test .

# Test specific feature
devcontainer features test -f jetify-devbox .

# Test specific scenario
devcontainer features test -f jetify-devbox --skip-autogenerated .

# Test with specific base image
devcontainer features test -f jetify-devbox --base-image ubuntu:focal .

# Run only global scenarios
devcontainer features test --global-scenarios-only .

Development Setup

# Install devcontainer CLI (required for testing)
npm install -g @devcontainers/cli

Architecture

Feature Structure

  • src/jetify-devbox/: Feature implementation

    • devcontainer-feature.json: Feature metadata defining options and dependencies
    • install.sh: Installation script that installs Devbox via Nix
    • ReadMe.md: Feature-specific documentation

  • test/jetify-devbox/: Feature tests

    • test.sh: Basic functionality tests
    • scenarios.json: Test scenarios configuration
    • test_*.sh: Scenario-specific test scripts
    • devbox.json: Sample Devbox configuration for testing

Installation Flow

  1. Nix dependency is installed automatically (via dependsOn)
  2. install.sh runs during container build:
    • Adds Nix unstable channel
    • Installs Devbox using Nix profile
    • Creates post-setup script at /usr/local/share/devbox-post-setup.sh
    • Creates manual setup helper at /usr/local/bin/devbox-setup
  3. Post-setup script runs on container creation via onCreateCommand:
    • Checks for devbox.json in workspace
    • Runs devbox update to initialize environment
    • Configures shell environment

Key Implementation Details

Feature Options

  • autoUpdate (boolean, default: true): Controls whether devbox update runs automatically

Environment Variables

  • DEVBOX_FEATURE_INSTALLED: Set to "true" in container environment
  • WORKSPACE_FOLDER: Used to locate devbox.json
  • _REMOTE_USER: Used to run commands as non-root user

Scripts Created

  • /usr/local/share/devbox-post-setup.sh: Runs on container creation
  • /usr/local/bin/devbox-setup: Manual setup helper
  • /usr/local/share/devbox-auto-update-enabled: Stores autoUpdate preference

Testing Architecture

The test suite verifies:

  1. Basic functionality (test.sh):

    • Devbox installation
    • PATH configuration
    • Basic commands (devbox version, devbox init, devbox shell)

  2. Scenario tests:

    • auto_update_enabled: Verifies automatic setup with devbox.json
    • auto_update_disabled: Verifies manual setup workflow
    • test_vscode_integration: Tests VS Code terminal integration
    • test_with_user_oncreate: Ensures compatibility with user onCreateCommand
    • test_different_base_images: Tests various base image compatibility

CI/CD Pipeline

GitHub Actions workflow (.github/workflows/test.yaml):

  • Tests against multiple base images (Alpine, Debian, Ubuntu, devcontainers/base)
  • Runs autogenerated tests, scenario tests, and global tests
  • Uploads test logs on failure for debugging

Important Patterns

  1. Shell Script Safety: All scripts use set -e for error handling
  2. User Context: Scripts handle both root and non-root execution
  3. Logging: Post-setup script logs to /tmp/devbox-setup.log
  4. Idempotency: Scripts check for existing configurations before running
  5. Feature ID: The feature ID is jetify-devbox (not just devbox)