Complete ext-env-check extension as showcase for extension development

[miohansen]

Overview

The ext-env-check extension at C:\source\ready-to-release\ext-env-check is intended to showcase how to create a clie extension. The extension has core functionality implemented but needs completion of deployment, workflow configuration, and documentation to serve as a proper reference implementation.

Repository: https://github.com/ready-to-release/ext-env-check (if separate repo) or local directory

Current State

✅ Completed Components

Core Implementation:

• Go CLI implementation in go/ext-env-check/
• Dockerfile with multi-stage build (containers/ext-env-check/Dockerfile)
• Comprehensive README with usage examples
• BDD specifications in specs/ext-env-check/
• CHANGELOG.md with version 0.1.0

Configuration Files:

• .eac/repository.yml - Module configuration with docker_build settings
• .eac/ai-provider.yml - AI provider configuration
• .github/workflows/ci-ext-env-check.yaml - CI workflow
• .github/workflows/release-ext-env-check.yaml - Release workflow
• .github/actions/ - All required GitHub actions present

Features Implemented:

• Environment variable checking with multiple modes
• JSON output support
• Extension metadata via extension-meta command
• Docker container support
• Test coverage

Missing Work

1. Container Deployment to Registry

Problem: Extension container has never been published to GHCR (GitHub Container Registry).

Required:

• First release: Create tag ext-env-check/0.1.0
• Verify CI workflow builds and tests container successfully
• Verify release workflow publishes to ghcr.io/ready-to-release/ext-env-check:0.1.0
• Verify container tags created: :0.1.0, :latest
• Test pulling and running published container

Expected Registry URL: ghcr.io/ready-to-release/ext-env-check

Verification Commands:

# Pull and test published container
docker pull ghcr.io/ready-to-release/ext-env-check:0.1.0
docker run --rm ghcr.io/ready-to-release/ext-env-check:0.1.0 --version
docker run --rm -e TEST_VAR=value ghcr.io/ready-to-release/ext-env-check:0.1.0 TEST_VAR

2. Workflow Configuration Verification

Problem: Workflows reference GitHub actions but need end-to-end testing.

Required:

• Verify CI workflow runs successfully on push to main
• Verify release workflow triggers on tag creation
• Confirm GitHub actions are properly configured:
  • build-container - Builds and pushes CI image
  • approve-release - Validates release preconditions
  • attested-container-publish - Publishes release container with attestation
  • cleanup-failed-release - Cleans up failed releases
  • setup-commands - Sets up eac commands binary
• Test workflow_dispatch manual trigger
• Verify workflow summaries generate correctly

CI Workflow (ci-ext-env-check.yaml):

• Builds container image
• Pushes to GHCR as ghcr.io/ready-to-release/ext-env-check:ci and sha-{short_sha}
• Runs container health check via extension-meta command
• Generates CI summary

Release Workflow (release-ext-env-check.yaml):

• Triggered by tags matching ext-env-check/*
• Validates CI passed for commit
• Retags and publishes container with version tags
• Creates GitHub Release with release notes
• Generates release summary

3. .eac Folder Configuration

Problem: Configuration needs documentation and verification for showcase purposes.

Current Configuration (.eac/repository.yml):

repository:
  type: mono

modules:
  - moniker: ext-env-check
    name: Environment Variable Check Extension
    type: container
    versioning:
      scheme: SemVer
    docker_build:
      container: "{moniker}"
      platforms:
        - linux/amd64
        - linux/arm64
      tags:
        - "ghcr.io/ready-to-release/{moniker}:ci"
        - "ghcr.io/ready-to-release/{moniker}:sha-{short_sha}"
      registry: ghcr.io

Required:

• Verify all paths in repository.yml are correct
• Confirm docker_build configuration matches Dockerfile location
• Test eac build ext-env-check builds successfully
• Validate workflow file paths are correct
• Document configuration patterns for extension developers

Additional Configuration Files:

• .clie/clie.yml - Extension installation configuration
• .eac/ai-provider.yml - AI generation settings

4. Showcase Documentation

Problem: No documentation explaining how this extension was created or how to replicate it.

Required Documentation (in ext-env-check repo):

A. Extension Development Guide (docs/development/creating-extensions.md):

# Creating clie Extensions

This document explains how ext-env-check was created as a reference.

## Extension Structure
- Directory layout
- Required files and configuration
- Module type: container vs binary

## Repository Setup
- .eac/repository.yml configuration
- Module definition
- Docker build configuration

## Workflow Configuration
- CI workflow setup
- Release workflow setup
- Required GitHub actions

## Container Development
- Dockerfile patterns
- Multi-stage builds
- Extension metadata command

## Testing Strategy
- BDD specifications
- Container health checks
- End-to-end testing

## Release Process
- Semantic versioning
- Changelog-based releases
- Container registry publishing

B. Step-by-Step Tutorial (docs/tutorials/extension-from-scratch.md):

# Building a clie Extension from Scratch

Follow this tutorial to create your own extension using ext-env-check as reference.

## Prerequisites
- clie installed
- Docker
- GitHub repository

## Step 1: Repository Setup
## Step 2: Module Configuration
## Step 3: Implementation
## Step 4: Containerization
## Step 5: CI/CD Setup
## Step 6: First Release
## Step 7: Testing and Validation

C. Configuration Reference (docs/reference/extension-configuration.md):

• Complete .eac/repository.yml reference
• Workflow configuration options
• Docker build settings
• Platform support

5. Installation and Usage Validation

Problem: Need to verify complete user journey from discovery to usage.

Required:

• Publish extension metadata to registry
• Test installation via clie install ext-env-check
• Verify extension appears in clie extensions list
• Test uninstallation via clie uninstall ext-env-check
• Validate .clie/clie.yml configuration pattern
• Document troubleshooting for common issues

Expected User Journey:

# Discovery
clie extensions search env

# Installation
clie install ext-env-check

# Usage
clie ext-env-check HOME USER SHELL

# Update
clie update ext-env-check

# Uninstall
clie uninstall ext-env-check

Implementation Plan

Phase 1: Deployment (High Priority)

1. Create First Release:

   • Review and finalize CHANGELOG.md for v0.1.0
   • Create tag: git tag ext-env-check/0.1.0
   • Push tag: git push origin ext-env-check/0.1.0
   • Monitor release workflow execution

2. Verify Container Publishing:

   • Check GHCR for published container
   • Test pulling and running container
   • Verify all tags present (0.1.0, latest, sha-*)
   • Test on both linux/amd64 and linux/arm64 platforms

3. Test GitHub Release:

   • Verify release created at https://github.com/ready-to-release/ext-env-check/releases
   • Check release notes generated correctly
   • Validate container pull instructions in release

Phase 2: Workflow Validation (High Priority)

1. CI Workflow Testing:

   • Make a test commit to trigger CI
   • Verify container builds successfully
   • Confirm health check passes (extension-meta command)
   • Review workflow summary output

2. Release Workflow Testing:

   • Create a patch release (v0.1.1) to test workflow
   • Verify CI validation step
   • Confirm container retagging and attestation
   • Test cleanup on failure scenario

3. Documentation Updates:

   • Document workflow requirements in README
   • Add troubleshooting section for common workflow issues
   • Update release process with actual experience

Phase 3: Configuration Showcase (Medium Priority)

1. Configuration Documentation:

   • Document each field in .eac/repository.yml
   • Explain docker_build configuration
   • Show platform support setup
   • Document workflow file paths

2. Configuration Templates:

   • Create template repository.yml for new extensions
   • Provide workflow templates
   • Include Dockerfile best practices

3. Validation:

   • Test configuration with eac commands
   • Verify build command works: eac build ext-env-check
   • Test all repository.yml features

Phase 4: Showcase Documentation (Medium Priority)

1. Development Guide:

   • Write comprehensive extension development guide
   • Include decision rationale (why container vs binary)
   • Document patterns and best practices
   • Add troubleshooting section

2. Tutorial Creation:

   • Create step-by-step tutorial
   • Include code examples
   • Add screenshots/diagrams
   • Test tutorial by following it

3. Reference Documentation:

   • Complete configuration reference
   • API documentation for extension-meta
   • Workflow configuration reference
   • Platform support matrix

Phase 5: Installation Validation (Low Priority)

1. Installation Testing:

   • Test clie install ext-env-check
   • Verify local configuration updates
   • Test extension discovery
   • Validate uninstallation

2. User Journey Validation:

   • Walk through complete user journey
   • Document expected behavior at each step
   • Create troubleshooting guide
   • Add FAQ section

Success Criteria

• Container published to ghcr.io/ready-to-release/ext-env-check:0.1.0
• Container pullable and executable on linux/amd64 and linux/arm64
• CI workflow runs successfully on every commit
• Release workflow publishes containers on tag creation
• GitHub Release created with correct release notes
• All .eac/ configuration documented and validated
• Extension development guide published
• Step-by-step tutorial available
• Configuration reference documentation complete
• Installation via clie install works end-to-end
• Extension serves as reference for other developers

Additional Context

Why This Matters:

• First reference implementation for clie extension development
• Showcases end-to-end extension lifecycle
• Validates extension tooling and workflows
• Provides template for future extensions
• Documents extension development process

Related Work:

• ext-eac extension (more complex, harder to use as reference)
• clie extension system
• Container registry integration
• Semantic versioning and changelog system

Priority: High

• Needed to validate extension system works
• Required for external extension developers
• Demonstrates clie capabilities
• Foundation for extension ecosystem

Testing Plan

Manual Testing Checklist:

• Build container locally: docker build -t ext-env-check:test -f containers/ext-env-check/Dockerfile .
• Run container locally: docker run --rm ext-env-check:test --version
• Test extension-meta: docker run --rm ext-env-check:test extension-meta
• Test CI workflow on test branch
• Test release workflow with test tag
• Pull from GHCR and verify
• Test on ARM64 platform (if available)
• Validate installation flow
• Follow tutorial documentation

Automated Testing:

• CI workflow includes container health check
• Release workflow includes validation steps
• GitHub actions provide automated testing

Repository Location

Current Location: C:\source\ready-to-release\ext-env-check

Expected GitHub Repository:

• Option 1: Separate repo at https://github.com/ready-to-release/ext-env-check
• Option 2: Subdirectory/worktree in main eac repo

Clarification Needed: Confirm repository structure for extensions.