Testing in External Repositories

Problem:

You want to test your clie extension in a different repository to ensure it works correctly outside of the EAC development environment.

Solution:

Build a local Docker image in the EAC repository, then configure external repositories to use it.

Overview

Extension Types

This guide covers testing two types of extensions in external repositories:

1. eac-ext: The EAC command extension (built in EAC repository)
2. Standalone extensions: Custom extensions like ext-env-check (separate repositories)

Both types use Docker-based testing in external repositories, but they're built differently.

Why Test in External Repositories?

Testing in external repositories ensures your extension:

• Works with real-world repository structures
• Handles different configuration scenarios
• Functions correctly outside the development environment
• Integrates properly with existing workflows
• Validates Dockerfile and container configuration
• Verifies cross-repository compatibility

Development vs Testing Workflow

This guide focuses on eac-ext, but the same principles apply to standalone extensions.

See the Testing Standalone Extensions section for standalone-specific guidance.

Workflow Summary:

1. Develop and debug in EAC repository using importer.ps1
2. Build Docker image when ready to test
3. Set up external repositories to use the local Docker image
4. Test in realistic environments

Prerequisites

Before testing in external repositories:

1. Complete development in EAC repository using importer.ps1:

cd C:\source\ready-to-release\eac
.\importer.ps1

1. Build local Docker image when ready for external testing:

cd C:\source\ready-to-release\eac
.\scripts\pwsh\local-dev\build-local.ps1

1. Ensure clie binary is installed (importer.ps1 handles this automatically)

2. Have a target external repository (with git initialized)

Quick Start

Set up an external repository in one command:

# Navigate to the external repository
cd C:\path\to\external-repo

# Run setup from EAC repository
C:\source\ready-to-release\eac\scripts\pwsh\local-dev\setup.ps1 -TargetRepo .

This configures the external repository to use your local Docker image.

Rebuilding Docker Image After Code Changes

After making code changes in the EAC repository, rebuild and test:

# 1. Navigate to EAC repository
cd C:\source\ready-to-release\eac

# 2. Rebuild Docker image
.\scripts\pwsh\local-dev\build-local.ps1

# 3. Test in external repo (no reconfiguration needed)
cd C:\path\to\external-repo
$env:CLIE_REPO_ROOT = (Get-Location)
clie eac <command>

That's it! External repositories automatically use the updated image.

Step-by-Step Setup

1. Navigate to Target Repository

cd C:\path\to\external-repo

Requirements:

• Directory must be a git repository
• If not, initialize git first:

git init

2. Run Setup Script

From the target repository, run the setup script from the EAC repository:

C:\source\ready-to-release\eac\scripts\pwsh\local-dev\setup.ps1 -TargetRepo .

Options:

3. Set Environment Variable

For each terminal session in the external repository:

# Set to current directory
$env:CLIE_REPO_ROOT = (Get-Location)

# Or set explicitly
$env:CLIE_REPO_ROOT = "C:\path\to\external-repo"

Important: This must be set in every new terminal session.

4. Initialize EAC Configuration

Initialize the EAC configuration in the external repository:

clie eac init

Follow the prompts to configure:

• AI provider (Claude API, OpenAI, or Gemini)
• API tokens
• Git integration

5. Test Commands

Run EAC commands to verify the setup:

# View available commands
clie eac help

# Show module information
clie eac show modules

Setup Verification

Check Configuration Files

Verify the configuration files were created:

# Check clie local config
cat .eac\eac.local.yml

# Check EAC config (after clie eac init)
cat .eac\eac\agent.yml

Verify Docker Image

Confirm the local Docker image is available:

docker images eac-ext:dev

Test Command Execution

Run a simple command to ensure everything works:

clie eac show modules

Testing Workflow

1. Test Basic Operations

# Initialize repository analysis
clie eac init

# View modules
clie eac show modules

# View available commands
clie eac help

2. Test AI Integration

# Create specification with AI
clie eac create spec "description of feature"

# Generate changelog
clie eac release changelog

3. Test Build and Validation

# Validate dependencies
clie eac validate dependencies

# Run tests
clie eac test <module-name>

Multiple External Repositories

Using the Same Local Image

Configure multiple repositories to use the same local image:

# Repository 1
cd C:\repos\project-a
C:\source\ready-to-release\eac\scripts\pwsh\local-dev\setup.ps1 -TargetRepo . -SkipBuild

# Repository 2
cd C:\repos\project-b
C:\source\ready-to-release\eac\scripts\pwsh\local-dev\setup.ps1 -TargetRepo . -SkipBuild

# Repository 3
cd C:\repos\project-c
C:\source\ready-to-release\eac\scripts\pwsh\local-dev\setup.ps1 -TargetRepo . -SkipBuild

Note: Use -SkipBuild to avoid rebuilding the Docker image for each repository.

Managing Configurations

Each repository maintains its own configuration:

project-a/
  .eac/
    eac.local.yml       # Points to eac-ext:dev
    eac/
      agent.yml             # Project A specific config

project-b/
  .eac/
    eac.local.yml       # Points to eac-ext:dev
    eac/
      agent.yml             # Project B specific config

Updating the Docker Image

After Code Changes

When you make changes to the EAC extension:

1. Develop with importer.ps1 first for fast iteration:

cd C:\source\ready-to-release\eac

# Run importer to set up session
.\importer.ps1

# Make code changes, then test immediately
eac <command>

1. Rebuild the Docker image when ready to test in external repos:

cd C:\source\ready-to-release\eac
.\scripts\pwsh\local-dev\build-local.ps1

1. Test in external repository (no reconfiguration needed):

cd C:\path\to\external-repo
$env:CLIE_REPO_ROOT = (Get-Location)
clie eac <command>

The external repository automatically uses the updated image.

Recommended Iteration Pattern

Testing Standalone Extensions in External Repos

If you're developing a standalone extension (like ext-env-check) and want to test it in external repos, follow this workflow.

Prerequisites

1. Your extension repository with Dockerfile
2. External test repository (different from your extension repo)
3. clie CLI installed

Quick Start

1. Build your extension locally:

cd C:\path\to\your-extension
docker build -f containers\your-extension\Dockerfile -t your-extension:dev .

2. Navigate to external test repo:

cd C:\path\to\external-test-repo

3. Create local clie config:

# .clie/clie.local.yml
version: "1.0"
extensions:
  - name: your-extension
    image: your-extension:dev
    load_local: true
    image_pull_policy: Never

4. Test:

clie your-extension --help
clie your-extension <command>

Iteration Workflow

After making changes to your extension:

1. Rebuild container in extension repo:

cd C:\path\to\your-extension
docker build -f containers\your-extension\Dockerfile -t your-extension:dev .

1. Test immediately in external repo (no reconfiguration needed):

cd C:\path\to\external-test-repo
clie your-extension <command>

Multiple Test Repositories

Test your extension in different repository structures:

# Build once
cd C:\path\to\your-extension
docker build -f containers\your-extension\Dockerfile -t your-extension:dev .

# Test in monorepo
cd C:\repos\test-monorepo
# Create .clie/clie.local.yml
clie your-extension <command>

# Test in single-module repo
cd C:\repos\test-single-module
# Create .clie/clie.local.yml
clie your-extension <command>

# Test in polyglot repo
cd C:\repos\test-polyglot
# Create .clie/clie.local.yml
clie your-extension <command>

Testing with Repository Access

Extensions that need repository access receive it automatically:

# Extension receives repository mounted at /var/task
clie your-extension <command>

The clie CLI automatically mounts the current directory at /var/task in the container.

Example: Testing ext-env-check

# 1. Build ext-env-check
cd C:\source\ready-to-release\ext-env-check
docker build -f containers\ext-env-check\Dockerfile -t ext-env-check:dev .

# 2. Create test repo
cd C:\temp\test-project
git init

# 3. Configure clie
New-Item -ItemType Directory -Force .clie
@"
version: "1.0"
extensions:
  - name: env-check
    image: ext-env-check:dev
    load_local: true
    image_pull_policy: Never
"@ | Out-File -FilePath .clie\clie.local.yml -Encoding UTF8

# 4. Test
clie env-check HOME USER SHELL

Comparing Extension Testing

Testing Different Versions

Test different image versions by using tags:

# Build image with version tag
cd C:\source\ready-to-release\eac
.\scripts\pwsh\local-dev\build-local.ps1 -Tag "eac-ext:test-v2"

# Configure external repo to use it
cd C:\path\to\external-repo
.\scripts\pwsh\cli\init-local.ps1 -ImageTag "eac-ext:test-v2" -Force

Related Guides

• Local Development Workflows - Learn about importer.ps1 and Docker workflows
• Creating Extensions - Learn how clie extensions work

Tutorials | How-to Guides | Explanation | Reference

You are here: How-to Guides — task-oriented recipes that guide you through solving specific problems.