README.md

Phellams-Automator

About The Project

Phellams-Automator is a multi-language build environment based on Debian 12 slim. It integrates with the Automator-Devops suite and can also be used as a standalone CI/CD runner image.

---

Features & Capabilities

Automation Toolchain

• PowerShell Pipeline: Automated module packaging into directory structures, .zip archives, or .nupkg artifacts via Psmpacker.
• Version Management: Automated Semantic Versioning orchestration via GitAutoVersion.
• Documentation Engine: Native man-page and help-file generation via Phwriter.
• Integrity Verification: Automated checksum generation and verification via CSVerify.

Multi-Language Build Systems

• .NET: Native execution support for dotnet build and dotnet pack targetting SDK v8 and v10 (including AOT compilation targets).
• Package Management: Native nuget pack capabilities coupled with custom Nupsforge cmdlets for multi-repository distribution (GitLab, Chocolatey, ProGet).
• JavaScript / TypeScript: Native execution handled via Bun for high-velocity runtime performance (replacing standard Node.js).
• Systems Languages: Built-in toolchains for Rust, Go, and Elixir.
• Ruby / Jekyll: Optimized runner configuration featuring integrated Bundler with CI hardening policies:
• Overridden BUNDLE_SILENCE_ROOT_WARNING: "1"
• Enforced deterministic dependency pathing via BUNDLE_PATH: "vendor/bundle"
• Pre-baked system dependencies (ruby-dev, build-essential) to eliminate runtime compilation failures.

CI/CD & DevOps Integration

• Native optimization for GitLab CI execution runners.
• Pre-configured, zero-dependency coverage upload targets for Codecov and Coveralls.

Feature Matrix & Roadmap

Capability	Component / Runtime	Status
PowerShell Core	Module packaging, testing, and distribution	Available
.NET Toolchain	Compilation, packing, and AOT support	Available
Bun Runtime	JavaScript and TypeScript execution	Available
Node.js Runtime	Node.js and npm	Available
Inkscape & ImageMagick	Media conversion and export	Available
DevOps Pipelines	Codecov and Coveralls clients	Available
PHP 8 Ecosystem	PHP, Composer, and Xdebug	Available
Python Runtime	Python 3 runtime	Available

---

Image Manifest

System Binaries

• .NET SDK v8.0.412 and v10.0.301
• PowerShell Core 7.6.4
• Bun Runtime
• Node & NPM Runtime
• NuGet 6.x (via Mono)
• Go Compiler
• Rust Toolchain
• Elixir Runtime
• Ruby & Jekyll (with hardened Bundler toolset)
• PHP & Composer (Native PHP8 runtime & package manager)
• ImageMagick & Inkscape (Media conversion & high-fidelity graphics)
• jq & yq (JSON & YAML processors)
• Photino.NET (Pre-cached .NET lightweight GUI desktop runtime)
• Codecov / Coveralls CLI

Pre-Baked PowerShell Modules

• Pester & PSScriptAnalyzer (Testing & Static Analysis)
• PowerShell-Yaml (Data Serialization)
• ColorConsole & Quicklog (UI Layout & High-Performance Logging)
• Tadpol (Runspace Progress Bars & Spinners)
• ShellDock (Isolated Runspace Executor)
• Nupsforge, Psmpacker, CSVerify, GitAutoVersion (Core Build Stack)

---

Build and Local Usage

Building the Image Locally

Build the image from the repository root:

# Repository root (Bash, Zsh, or WSL)
docker buildx build --load \
  --tag phellams-automator:localbuild \
  --file phellams-automator.dockerfile \
  .

The --load option makes the result available to docker run when the selected Buildx driver does not load images automatically.

Alternatively, use the local PowerShell builder:

# Repository root (PowerShell 7)
./phellams-automator-local-builder.ps1 -BuildMode Base

Image Information

The image starts PowerShell when no command is supplied:

# Bash, Zsh, or WSL
docker run --rm docker.io/sgkens/phellams-automator:latest

Print the installed runtime and module information:

# Bash, Zsh, or WSL
docker run --rm docker.io/sgkens/phellams-automator:latest \
  pwsh -NoProfile -Command \
  'Get-Module -ListAvailable | Sort-Object Name, Version | Format-Table Name, Version'

Mounting the Current Project

Use /workspace as the container path and set it as the working directory:

# Bash, Zsh, or WSL
docker run --rm --interactive --tty \
  --volume "$(pwd):/workspace" \
  --workdir /workspace \
  docker.io/sgkens/phellams-automator:latest

# Windows, macOS, or Linux PowerShell
docker run --rm --interactive --tty `
  --volume "${PWD}:/workspace" `
  --workdir /workspace `
  docker.io/sgkens/phellams-automator:latest

Docker Desktop must have WSL integration enabled when these commands are run from a WSL distribution.

Running a Project Script

# Bash, Zsh, or WSL
docker run --rm \
  --volume "$(pwd):/workspace" \
  --workdir /workspace \
  docker.io/sgkens/phellams-automator:latest \
  pwsh -NoProfile -File ./myscript.ps1

PowerShell Test and Build Commands

PowerShell cmdlets must be passed to pwsh -Command; they are not standalone Linux executables.

# Run all Pester tests below ./tests
docker run --rm \
  --volume "$(pwd):/workspace" \
  --workdir /workspace \
  docker.io/sgkens/phellams-automator:latest \
  pwsh -NoProfile -Command 'Invoke-Pester -Path ./tests'

# Analyze all PowerShell files in the project
docker run --rm \
  --volume "$(pwd):/workspace" \
  --workdir /workspace \
  docker.io/sgkens/phellams-automator:latest \
  pwsh -NoProfile -Command 'Invoke-ScriptAnalyzer -Path . -Recurse'

# Return the GitAutoVersion version
docker run --rm \
  --volume "$(pwd):/workspace" \
  --workdir /workspace \
  docker.io/sgkens/phellams-automator:latest \
  pwsh -NoProfile -Command '(Get-GitAutoVersion).Version'

# Return a version calculated from Conventional Commits
docker run --rm \
  --volume "$(pwd):/workspace" \
  --workdir /workspace \
  docker.io/sgkens/phellams-automator:latest \
  pwsh -NoProfile -Command 'Get-ConventionalCommitVersion'

The bundled custom modules export the following commands:

Module	Exported commands
ColorConsole	New-ColorConsole, Write-Color
ConventionalCommitVersion	Get-ConventionalCommitVersion
CSVerify	New-CheckSum, New-VerificationFile, Read-CheckSum, Test-Verification
GitAutoVersion	Get-GitAutoVersion
Nupsforge	New-ChocoNuspecFile, New-ChocoPackage, New-NupkgIcon, New-NupkgPackage, New-NuspecPackageFile
PHWriter	New-PHWriter, Write-PHAsciiLogo
Psmpacker	Build-Module
Quicklog	Get-QuicklogTypes, New-Quicklog, Write-Quicklog, Write-QuicklogProgress
ShellDock	New-ShellDock
Tadpol	Clear-Prelines, Get-TPThemes, New-TPObject, Write-TPProgress

Inspect a command's syntax and examples before using it:

# Replace Build-Module with any exported command listed above
docker run --rm docker.io/sgkens/phellams-automator:latest \
  pwsh -NoProfile -Command 'Get-Help Build-Module -Full'

Native Toolchain Commands

All examples mount the current project at /workspace.

# .NET
docker run --rm -v "$(pwd):/workspace" -w /workspace \
  docker.io/sgkens/phellams-automator:latest dotnet build

# NuGet
docker run --rm -v "$(pwd):/workspace" -w /workspace \
  docker.io/sgkens/phellams-automator:latest nuget pack ./package.nuspec

# Bun
docker run --rm -v "$(pwd):/workspace" -w /workspace \
  docker.io/sgkens/phellams-automator:latest bun test

# Node.js and npm
docker run --rm -v "$(pwd):/workspace" -w /workspace \
  docker.io/sgkens/phellams-automator:latest npm test

# Go
docker run --rm -v "$(pwd):/workspace" -w /workspace \
  docker.io/sgkens/phellams-automator:latest go test ./...

# Rust
docker run --rm -v "$(pwd):/workspace" -w /workspace \
  docker.io/sgkens/phellams-automator:latest rustc --version

# Elixir
docker run --rm -v "$(pwd):/workspace" -w /workspace \
  docker.io/sgkens/phellams-automator:latest elixir --version

# Ruby and Jekyll
docker run --rm -v "$(pwd):/workspace" -w /workspace \
  docker.io/sgkens/phellams-automator:latest bundle exec jekyll build

# PHP and Composer
docker run --rm -v "$(pwd):/workspace" -w /workspace \
  docker.io/sgkens/phellams-automator:latest composer install

# Inkscape
docker run --rm -v "$(pwd):/workspace" -w /workspace \
  docker.io/sgkens/phellams-automator:latest \
  inkscape ./image.svg --export-filename=./image.png

# ImageMagick
docker run --rm -v "$(pwd):/workspace" -w /workspace \
  docker.io/sgkens/phellams-automator:latest \
  convert ./image.png -resize 50% ./image-small.png

# jq and yq
docker run --rm -v "$(pwd):/workspace" -w /workspace \
  docker.io/sgkens/phellams-automator:latest jq . ./data.json
docker run --rm -v "$(pwd):/workspace" -w /workspace \
  docker.io/sgkens/phellams-automator:latest yq . ./data.yaml

# Codecov and Coveralls
docker run --rm -v "$(pwd):/workspace" -w /workspace \
  docker.io/sgkens/phellams-automator:latest codecov --help
docker run --rm -v "$(pwd):/workspace" -w /workspace \
  docker.io/sgkens/phellams-automator:latest coveralls --help

Automation Script Parameters

phellams-automator-local-builder.ps1 accepts one mandatory parameter:

Parameter	Type	Accepted values	Description
-BuildMode	String	Base, choco	Selects the Dockerfile and local image tag used by the builder.

---

Contributing & License

Contributing

1. Fork the Project.
2. Create your Feature Branch (git checkout -b feature/AmazingFeature).
3. Commit your Changes (git commit -m 'feat: Add AmazingFeature').
4. Push to the Branch (git push origin feature/AmazingFeature).
5. Open a Merge Request.

License

Distributed under the MIT License. See LICENSE for more information.

---