javi-forge 1.6.1 → 1.7.0

package/README.md

@@ -88,8 +88,12 @@ flowchart LR
 | `ci` | Run CI simulation (lint + compile + test + security + ghagga) |
 | `ci init` | Install git hooks in `.git/hooks/` (recommended for existing repos) |
 | `tdd init` | Install TDD-enforcing pre-commit hook (auto-detects stack) |
+| `tdd pipeline` | Install full TDD pipeline (red → green → refactor enforcement) |
 | `analyze` | Run repoforge skills analysis on current project |
 | `doctor` | Show comprehensive health report |
+| `workflow show` | Print the active workflow definition |
+| `workflow validate` | Lint the workflow YAML against the schema |
+| `workflow list` | List bundled workflow templates |
 | `plugin add` | Install a plugin from GitHub (`org/repo`) |
 | `plugin remove` | Remove an installed plugin |
 | `plugin list` | List installed plugins |
@@ -98,8 +102,11 @@ flowchart LR
 | `plugin sync` | Auto-detect and wire installed plugins into manifest |
 | `plugin export` | Export plugin to Agent Skills spec (`skills.json`) |
 | `plugin export --codex` | Export plugin to Codex-compatible TOML subagent files |
+| `plugin export-skills` | Aggregate all installed plugin skills into a single bundle |
 | `plugin import` | Import an Agent Skills spec package as a javi-forge plugin |
 | `skills doctor` | Show skills health report (conflict + duplicate detection) |
+| `skills auto` | Scan project lockfiles and auto-install matching skills from the registry |
+| `skill publish` | Publish a local skill to the registry (validates manifest, signs the artifact) |
 | `skills budget` | Show token cost of loaded skills |
 | `skills score` | Score a skill on quality dimensions (0-100) |
 | `skills benchmark` | Benchmark a skill with structural quality checks |
@@ -126,6 +133,43 @@ npx javi-forge security check
 npx javi-forge llms-txt
 ```
 
+### Mixed-stack CI (hybrid repositories)
+
+By default `ci` auto-detects a **single** stack from marker files — zero
+config, unchanged for single-stack repos. Hybrid repositories (e.g. Node
+frontend + Python backend) declare every toolchain in a versioned config,
+`.javi-forge/ci.yaml`:
+
+```yaml
+version: 1
+runners:
+  - name: backend
+    stack: python
+    directory: backend
+    setup: pip install -r requirements.txt
+    lint: ruff check .
+    test: pytest
+    requires: [python3, ruff, pytest]
+  - name: frontend
+    stack: node
+    lint: pnpm run lint
+    test: pnpm run test
+    requires: [node, pnpm]
+```
+
+Runners execute in order, each in its own directory and image, and every
+`requires` tool is verified fail-closed before any phase runs — a missing
+tool aborts with an explicit error instead of a skipped check. Custom
+images, digest pinning (`image: name@sha256:…`) and custom
+`build-context` Dockerfiles are supported.
+
+- `javi-forge ci --config <path>` — load explicit runners
+- `javi-forge ci --stack python` — force a single stack (single-stack
+  repos only; insufficient for hybrid repos)
+
+Full guide: [docs/ci-runners.md](docs/ci-runners.md) (config reference,
+migration from auto-detection, troubleshooting, trust boundary).
+
 ### CLI Flags
 
 | Flag | Type | Default | Description |
@@ -330,7 +374,7 @@ npx javi-forge doctor
 
 ## Requirements
 
-- **Node.js** >= 18
+- **Node.js** >= 22 (required by ink 7; previous versions ran on >= 18)
 
 ## Ecosystem
 

package/ci-local/README.md

@@ -15,6 +15,16 @@ Reproduce tu CI/CD localmente antes de push. Si pasa local → pasa en GitHub Ac
 
 ## Instalación (30 segundos)
 
+### Prerequisito obligatorio
+
+Los hooks invocan la CLI `javi-forge`. Instalala global ANTES de correr `install.sh`:
+
+```bash
+npm install -g javi-forge
+```
+
+Si estás desarrollando javi-forge mismo, usá `pnpm link --global` desde la raíz del workspace.
+
 ### Copiar a un proyecto nuevo
 
 ```bash
@@ -24,12 +34,25 @@ cp -r lib /path/to/new-project/
 
 # En el nuevo proyecto
 cd /path/to/new-project
-./.ci-local/install.sh      # Linux/Mac
+./.ci-local/install.sh      # Linux/Mac/WSL
 # o
-.\.ci-local\install.ps1     # Windows
+.\.ci-local\install.ps1     # Windows (PowerShell 7+)
 ```
 
-> **Importante:** CI-Local depende de `lib/common.sh` (funciones compartidas). Copiar siempre ambos directorios.
+> **Importante:** CI-Local depende de `lib/common.sh` (Linux/Mac) y/o `lib/common.psm1` (Windows). Copiá ambos junto con el directorio `ci-local/`.
+
+El installer (ambas variantes) falla con mensaje claro si `javi-forge` no está en el PATH.
+
+### Soporte cross-platform
+
+| Plataforma | Installer | Runner | Hooks | Requisitos |
+|---|---|---|---|---|
+| Linux | `install.sh` | `ci-local.sh` | bash | bash, perl, docker (opcional) |
+| macOS | `install.sh` | `ci-local.sh` | bash | bash, perl, docker (opcional) |
+| WSL | `install.sh` | `ci-local.sh` | bash | bash, perl, docker (opcional) |
+| Windows nativo | `install.ps1` | `ci-local.ps1` | bash | PowerShell 7+, Git for Windows (MSYS2 bash), docker (opcional) |
+
+Los git hooks (`pre-commit`, `commit-msg`, `pre-push`) son bash en todas las plataformas. En Windows nativo corren via el MSYS2 bash que viene con Git for Windows — no se necesita una versión PowerShell de los hooks.
 
 ### Dependencias opcionales
 
@@ -53,15 +76,37 @@ git commit -m "..."   # → pre-commit: AI check + lint + security (~30s)
 git push              # → pre-push: CI completo en Docker (~3min)
 ```
 
-### AI Attribution Blocker
+### AI Attribution Blocker (best-effort)
 
-Los hooks bloquean automáticamente:
-- `Co-authored-by: Claude`, `Co-authored-by: GPT`, etc.
-- `Made by Claude`, `Generated by AI`, `Written by GPT`
-- Referencias a `@anthropic.com`, `@openai.com`
-- Nombres de modelos: `claude opus`, `gpt-4`, `chatgpt`, etc.
+El hook `commit-msg` bloquea atribución accidental a herramientas de IA.
+**Es best-effort, no es un control de seguridad adversarial.**
+
+#### Qué bloquea
 
-**Tú eres el único autor de tu código.**
+- `Co-authored-by: Claude`, `Co-authored-by: GPT`, etc.
+- `Made/generated/written/built/produced by/with X` (con proveedores conocidos)
+- `X-assisted` (anthropic-assisted, openai-assisted, etc.)
+- Referencias a `@anthropic.com`, `@openai.com`, etc.
+- Nombres de modelos: `claude opus`, `gpt-4`, `chatgpt`, `claude-sonnet`, `Claude3.5`
+- AI IDEs: `Cursor`, `Windsurf`, `Codeium`, `Cody`, `Aider`
+- Variantes con whitespace doble, markdown (`**Claude**`), puntuación entre tokens,
+  emoji separadores, full-width latin (`Ｃｌａｕｄｅ`), combining diacritics (`Ćlaude`),
+  y Unicode invisibles (ZWSP/RLM/NBSP).
+
+#### Qué NO bloquea (limitaciones documentadas)
+
+- **Homoglifos cross-script**: `Сlaude` (Cyrillic), `Ϲlaude` (Greek), `Ꮯlaude` (Cherokee).
+  Requieren transliteración via módulos perl no-core.
+- **Tag characters / variation selectors**: `Made by\u{E0063}laude`. Rangos Unicode
+  específicos no estripeados.
+- **Bare provider name sin verbo prepositional**: "asked Claude to refactor",
+  "I used Claude for this", "claude helped me debug". El riesgo de false positive
+  en nombres personales o conversaciones legítimas es alto.
+
+Si tu modelo de amenaza requiere defensa contra adversarios motivados, usá
+**signed commits** + revisor humano. Un regex no es cripto.
+
+**Tú sos el único autor de tu código.**
 
 ### Manual
 
@@ -133,7 +178,7 @@ Developer workflow:
 
 lib/                  # Dependencia requerida (copiar junto con .ci-local/)
 ├── common.sh         # Funciones compartidas (Bash)
-└── Common.psm1       # Funciones compartidas (PowerShell)
+└── common.psm1       # Funciones compartidas (PowerShell)
 ```
 
 ## Personalización

package/ci-local/ci-local.ps1

@@ -0,0 +1,445 @@
+# =============================================================================
+# CI-LOCAL: Universal CI Simulation (PowerShell)
+# =============================================================================
+# Mirror of ci-local/ci-local.sh for Windows / PowerShell users.
+#
+# Usage:
+#   .\ci-local.ps1               # full CI
+#   .\ci-local.ps1 quick         # lint + compile only
+#   .\ci-local.ps1 shell         # interactive shell inside CI container
+#   .\ci-local.ps1 detect        # print detected stack and exit
+#
+# Behaviour MUST match ci-local.sh. Diff against the bash version on every
+# change.
+# =============================================================================
+
+#Requires -Version 7.2
+[CmdletBinding()]
+param(
+    [Parameter(Position = 0)]
+    [ValidateSet('full', 'quick', 'shell', 'detect')]
+    [string]$Mode = 'full'
+)
+
+# See install.ps1 for the rationale behind 7.2 minimum (ResolveLinkTarget).
+if ($PSVersionTable.PSEdition -ne 'Core' -or $PSVersionTable.PSVersion -lt [Version]'7.2') {
+    Write-Host 'ERROR: ci-local.ps1 requires PowerShell 7.2+ (pwsh).' -ForegroundColor Red
+    exit 1
+}
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$ScriptDir  = Split-Path -Parent $PSCommandPath
+$ProjectDir = Split-Path -Parent $ScriptDir
+
+# ─── Symlink-safe path resolver (inline, runs BEFORE Import-Module) ───
+# Same defense as install.ps1: remove any pre-existing alias/function with
+# this name (Alias > Function in PS lookup order would let a $PROFILE
+# alias shadow our resolver), then verify the binding is the local
+# function defined in THIS script file.
+Remove-Item Alias:Resolve-RealPath    -Force -ErrorAction SilentlyContinue
+Remove-Item Function:Resolve-RealPath -Force -ErrorAction SilentlyContinue
+function Resolve-RealPath([string]$P) {
+    if ([string]::IsNullOrEmpty($P)) { throw "Resolve-RealPath: empty path" }
+    $item = Get-Item -LiteralPath $P -Force -ErrorAction Stop
+    $target = $item.ResolveLinkTarget($true)
+    if ($target) {
+        if (-not $target.Exists) {
+            throw "Resolve-RealPath: dangling symlink target $($target.FullName)"
+        }
+        return $target.FullName
+    }
+    return $item.FullName
+}
+$_rr = Get-Command Resolve-RealPath -ErrorAction SilentlyContinue
+if (-not $_rr -or $_rr.CommandType -ne 'Function' -or $_rr.ScriptBlock.File -ne $PSCommandPath) {
+    Write-Host 'ERROR: Resolve-RealPath is shadowed by an external command' -ForegroundColor Red
+    exit 1
+}
+Remove-Variable _rr
+
+# ─── Load shared lib ──────────────────────────────────────────────────
+$libCandidates = @(
+    (Join-Path $ScriptDir 'lib' 'common.psm1')
+    (Join-Path $ScriptDir '..' 'lib' 'common.psm1')
+)
+$libPath = $libCandidates | Where-Object { Test-Path -LiteralPath $_ -PathType Leaf } | Select-Object -First 1
+if (-not $libPath) {
+    Write-Host 'ERROR: lib/common.psm1 not found' -ForegroundColor Red
+    exit 1
+}
+
+# SECURITY: validate the module BEFORE importing. Mirror of install.ps1.
+try {
+    $libReal     = Resolve-RealPath $libPath
+    $projectReal = Resolve-RealPath $ProjectDir
+} catch {
+    Write-Host "ERROR: could not resolve lib/common.psm1 or project root: $($_.Exception.Message)" -ForegroundColor Red
+    exit 1
+}
+$sep = [System.IO.Path]::DirectorySeparatorChar
+if (-not ($libReal.Equals($projectReal, [StringComparison]::OrdinalIgnoreCase) -or
+          $libReal.StartsWith($projectReal + $sep, [StringComparison]::OrdinalIgnoreCase))) {
+    Write-Host 'ERROR: lib/common.psm1 resolves outside the project root' -ForegroundColor Red
+    Write-Host "  LIB resolved:     $libReal" -ForegroundColor Yellow
+    Write-Host "  PROJECT resolved: $projectReal" -ForegroundColor Yellow
+    exit 1
+}
+
+Import-Module $libPath -Force
+
+# ─── Stack detection + per-stack CI commands ──────────────────────────
+function Get-CiConfig {
+    param([string]$ProjectDir)
+
+    $stack = Get-Stack -ProjectDir $ProjectDir
+
+    $cfg = @{
+        StackType   = $stack.StackType
+        BuildTool   = $stack.BuildTool
+        JavaVersion = $stack.JavaVersion
+        Dockerfile  = ''
+        LintCmd     = ''
+        CompileCmd  = ''
+        TestCmd     = ''
+    }
+
+    switch ($stack.StackType) {
+        'java-gradle' {
+            $cfg.Dockerfile = 'java.Dockerfile'
+            $cfg.LintCmd    = './gradlew spotlessCheck --no-daemon'
+            $cfg.CompileCmd = './gradlew clean classes testClasses --no-daemon && chown -R runner:runner build .gradle 2>/dev/null || true'
+            $cfg.TestCmd    = './gradlew test --no-daemon'
+        }
+        'java-maven' {
+            $cfg.Dockerfile = 'java.Dockerfile'
+            $cfg.LintCmd    = './mvnw spotless:check'
+            $cfg.CompileCmd = './mvnw clean compile test-compile && chown -R runner:runner target .mvn 2>/dev/null || true'
+            $cfg.TestCmd    = './mvnw test'
+        }
+        'node' {
+            $cfg.Dockerfile = 'node.Dockerfile'
+            $pkg = Join-Path $ProjectDir 'package.json'
+            $pkgRaw = Get-Content -LiteralPath $pkg -Raw -ErrorAction SilentlyContinue
+            if ($pkgRaw -and ($pkgRaw -match '"lint"'))      { $cfg.LintCmd    = "$($stack.BuildTool) run lint" }
+            if ($pkgRaw -and ($pkgRaw -match '"build"'))     { $cfg.CompileCmd = "rm -rf dist build && $($stack.BuildTool) run build && chown -R runner:runner dist build 2>/dev/null || true" }
+            if ($pkgRaw -and ($pkgRaw -match '"test"')) {
+                $cfg.TestCmd = "$($stack.BuildTool) test"
+                if ($pkgRaw -match '"test:hooks"') {
+                    $cfg.TestCmd = "$($cfg.TestCmd) && $($stack.BuildTool) run test:hooks"
+                }
+            }
+        }
+        'python' {
+            $cfg.Dockerfile = 'python.Dockerfile'
+            $cfg.LintCmd    = 'ruff check . && { pylint **/*.py 2>/dev/null || true; }'
+            $cfg.TestCmd    = 'pytest'
+        }
+        'go' {
+            $cfg.Dockerfile = 'go.Dockerfile'
+            $cfg.LintCmd    = 'golangci-lint run'
+            $cfg.CompileCmd = 'go clean -cache && go build ./... && chown -R runner:runner . 2>/dev/null || true'
+            $cfg.TestCmd    = 'go test ./...'
+        }
+        'rust' {
+            $cfg.Dockerfile = 'rust.Dockerfile'
+            $cfg.LintCmd    = 'cargo clippy -- -D warnings'
+            $cfg.CompileCmd = 'cargo clean && cargo build && chown -R runner:runner target 2>/dev/null || true'
+            $cfg.TestCmd    = 'cargo test'
+        }
+    }
+
+    return $cfg
+}
+
+# ─── Docker helpers ───────────────────────────────────────────────────
+function Get-ImageName {
+    param([string]$StackType)
+    "ci-local-$StackType"
+}
+
+function New-Dockerfile {
+    param([Parameter(Mandatory)][hashtable]$Cfg)
+
+    $dockerDir = Join-Path $ScriptDir 'docker'
+    New-Item -ItemType Directory -Force -Path $dockerDir | Out-Null
+    $target = Join-Path $dockerDir $Cfg.Dockerfile
+
+    # Heredoc bodies kept byte-identical to ci-local.sh so the image-hash
+    # cache aligns across platforms when the same Dockerfile is generated.
+    $content = switch ($Cfg.StackType) {
+        { $_ -in 'java-gradle','java-maven' } {
+@'
+ARG JAVA_VERSION=21
+FROM eclipse-temurin:${JAVA_VERSION}-jdk-noble
+RUN apt-get update && apt-get install -y git curl unzip && rm -rf /var/lib/apt/lists/*
+RUN useradd -m -s /bin/bash runner
+USER runner
+WORKDIR /home/runner/work
+ENV GRADLE_USER_HOME=/home/runner/.gradle
+ENTRYPOINT ["/bin/bash", "-c"]
+'@
+        }
+        'node' {
+@'
+FROM node:22-slim@sha256:689c11043dad91472750cd824c97dd5e2318e9dd6f954e492fe7af0135d33ceb
+RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
+RUN npm install -g pnpm
+RUN useradd -m -s /bin/bash runner
+USER runner
+WORKDIR /home/runner/work
+ENTRYPOINT ["/bin/bash", "-c"]
+'@
+        }
+        'python' {
+@'
+FROM python:3.12-slim@sha256:401f6e1a67dad31a1bd78e9ad22d0ee0a3b52154e6bd30e90be696bb6a3d7461
+RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
+RUN pip install --no-cache-dir pytest ruff pylint poetry
+RUN useradd -m -s /bin/bash runner
+USER runner
+WORKDIR /home/runner/work
+ENTRYPOINT ["/bin/bash", "-c"]
+'@
+        }
+        'go' {
+@'
+FROM golang:1.23-bookworm@sha256:167053a2bb901972bf2c1611f8f52c44d5fe7e762e5cab213708d82c421614db
+RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
+RUN go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.62.0 && \
+    mv /root/go/bin/golangci-lint /usr/local/bin/
+RUN useradd -m -s /bin/bash runner
+USER runner
+WORKDIR /home/runner/work
+ENTRYPOINT ["/bin/bash", "-c"]
+'@
+        }
+        'rust' {
+@'
+FROM rust:1.83-slim@sha256:540c902e99c384163b688bbd8b5b8520e94e7731b27f7bd0eaa56ae1960627ab
+RUN apt-get update && apt-get install -y git pkg-config libssl-dev && rm -rf /var/lib/apt/lists/*
+RUN rustup component add clippy rustfmt
+RUN useradd -m -s /bin/bash runner
+USER runner
+WORKDIR /home/runner/work
+ENTRYPOINT ["/bin/bash", "-c"]
+'@
+        }
+        default {
+@'
+FROM ubuntu:24.04@sha256:c4a8d5503dfb2a3eb8ab5f807da5bc69a85730fb49b5cfca2330194ebcc41c7b
+RUN apt-get update && apt-get install -y git curl && rm -rf /var/lib/apt/lists/*
+RUN useradd -m -s /bin/bash runner
+USER runner
+WORKDIR /home/runner/work
+ENTRYPOINT ["/bin/bash", "-c"]
+'@
+        }
+    }
+
+    # Write with LF line endings to match the bash output, so the
+    # dockerfile-hash label stays consistent between platforms.
+    [System.IO.File]::WriteAllText($target, ($content + "`n"), [System.Text.UTF8Encoding]::new($false))
+    Write-Host "Created $($Cfg.Dockerfile)" -ForegroundColor Green
+}
+
+function Confirm-DockerImage {
+    param([Parameter(Mandatory)][hashtable]$Cfg)
+
+    $imageName  = Get-ImageName -StackType $Cfg.StackType
+    $dockerfile = Join-Path $ScriptDir 'docker' $Cfg.Dockerfile
+
+    if (-not (Test-Path -LiteralPath $dockerfile -PathType Leaf)) {
+        Write-Host "Creating Dockerfile for $($Cfg.StackType)..." -ForegroundColor Yellow
+        New-Dockerfile -Cfg $Cfg
+    }
+
+    # SHA256 of the Dockerfile content — matches `sha256sum` from the bash version.
+    $hash = (Get-FileHash -LiteralPath $dockerfile -Algorithm SHA256).Hash.ToLowerInvariant()
+    $imageHash = ''
+    try {
+        $imageHash = & docker inspect --format='{{index .Config.Labels "dockerfile-hash"}}' $imageName 2>$null
+    } catch { }
+
+    if ($hash -ne $imageHash) {
+        Write-Host 'Building CI Docker image...' -ForegroundColor Yellow
+        $buildArgs = @('--label', "dockerfile-hash=$hash")
+        if ($Cfg.JavaVersion -and $Cfg.StackType -like 'java-*') {
+            $buildArgs += @('--build-arg', "JAVA_VERSION=$($Cfg.JavaVersion)")
+        }
+        & docker build @buildArgs -f $dockerfile -t $imageName (Join-Path $ScriptDir 'docker')
+        if ($LASTEXITCODE -ne 0) { throw 'docker build failed' }
+    }
+}
+
+# Convert a host path to the form expected by docker run -v.
+# Linux/macOS:  /path/to/x         -> /path/to/x  (pass through)
+# Windows:      C:\Users\foo\proj  -> /c/Users/foo/proj  (Docker Desktop format)
+# WSL inside Windows is the bash side and never reaches this code.
+function ConvertTo-DockerHostPath {
+    param([Parameter(Mandatory)][string]$Path)
+    if (-not $IsWindows) { return $Path }
+    # Drive letter + colon. Two forms exist:
+    #   C:\Users\foo  → absolute, valid for docker bind
+    #   C:Users\foo   → drive-relative, NOT a real absolute path
+    # Refuse the drive-relative form — it produces /cUsers/foo which is a
+    # broken bind mount and worth surfacing immediately.
+    if ($Path -match '^([A-Za-z]):(.*)$') {
+        $drive = $Matches[1].ToLowerInvariant()
+        $rest  = $Matches[2]
+        if (-not ($rest.StartsWith('/') -or $rest.StartsWith('\'))) {
+            throw "ConvertTo-DockerHostPath: drive-relative path not supported ($Path). Use an absolute path."
+        }
+        return "/$drive" + ($rest -replace '\\', '/')
+    }
+    return ($Path -replace '\\', '/')
+}
+
+function Invoke-InCi {
+    param(
+        [Parameter(Mandatory)][hashtable]$Cfg,
+        [Parameter(Mandatory)][string]$Cmd,
+        [string]$RunUser = 'runner'
+    )
+
+    $imageName = Get-ImageName -StackType $Cfg.StackType
+
+    $timeout = if ($env:CI_LOCAL_TIMEOUT) { $env:CI_LOCAL_TIMEOUT } else { '600' }
+    if ($timeout -notmatch '^\d+$') {
+        Write-Host "Error: CI_LOCAL_TIMEOUT must be a positive integer, got: $timeout" -ForegroundColor Red
+        exit 1
+    }
+
+    $dockerFlags = @('--rm')
+    # Allocate a TTY only when stdin is a real terminal. The bash version
+    # uses `[ -t 0 ]`; the PowerShell equivalent is IsInputRedirected from
+    # System.Console — older UserInteractive + RawUI checks are unreliable
+    # in pwsh 7 (flagged by audit round 3).
+    if (-not [Console]::IsInputRedirected) { $dockerFlags += '-it' }
+
+    $hostMount = ConvertTo-DockerHostPath -Path $ProjectDir
+    & docker run @dockerFlags `
+        --stop-timeout 30 `
+        --entrypoint '' `
+        --user $RunUser `
+        -v "${hostMount}:/home/runner/work" `
+        -e CI=true `
+        $imageName timeout $timeout bash -c $Cmd
+    if ($LASTEXITCODE -ne 0) { throw "step failed with exit $LASTEXITCODE" }
+}
+
+# ─── Main ─────────────────────────────────────────────────────────────
+Write-Host ''
+Write-Host '=== CI-LOCAL ===' -ForegroundColor Yellow
+
+$cfg = Get-CiConfig -ProjectDir $ProjectDir
+
+if ($cfg.StackType -eq 'unknown') {
+    Write-Host 'Could not detect project type!' -ForegroundColor Red
+    Write-Host 'Supported: Java/Gradle, Java/Maven, Node, Python, Go, Rust' -ForegroundColor Yellow
+    exit 1
+}
+
+Write-Host "Detected: $($cfg.StackType) ($($cfg.BuildTool))" -ForegroundColor Green
+if ($cfg.StackType -like 'java-*') {
+    Write-Host "Java version: $($cfg.JavaVersion)" -ForegroundColor Green
+}
+
+$ghaggaAvailable = Test-CommandExists -Name 'ghagga'
+
+switch ($Mode) {
+    'detect' {
+        Write-Host ''
+        Write-Host 'Stack details:' -ForegroundColor Cyan
+        Write-Host "  Type: $($cfg.StackType)"
+        Write-Host "  Build tool: $($cfg.BuildTool)"
+        Write-Host "  Dockerfile: $($cfg.Dockerfile)"
+        Write-Host "  Lint: $($cfg.LintCmd)"
+        Write-Host "  Compile: $($cfg.CompileCmd)"
+        Write-Host "  Test: $($cfg.TestCmd)"
+        exit 0
+    }
+
+    'quick' {
+        Confirm-DockerImage -Cfg $cfg
+        Write-Host ''
+        Write-Host 'Running quick check...' -ForegroundColor Yellow
+
+        if ($cfg.LintCmd) {
+            Write-Host "Lint: $($cfg.LintCmd)" -ForegroundColor Cyan
+            Invoke-InCi -Cfg $cfg -Cmd "cd /home/runner/work && $($cfg.LintCmd)"
+        }
+        if ($cfg.CompileCmd) {
+            Write-Host "Compile: $($cfg.CompileCmd)" -ForegroundColor Cyan
+            Invoke-InCi -Cfg $cfg -Cmd "cd /home/runner/work && $($cfg.CompileCmd)" -RunUser 'root'
+        }
+    }
+
+    'shell' {
+        Confirm-DockerImage -Cfg $cfg
+        Write-Host ''
+        Write-Host 'Opening shell in CI environment...' -ForegroundColor Yellow
+        $imageName = Get-ImageName -StackType $cfg.StackType
+        $hostMount = ConvertTo-DockerHostPath -Path $ProjectDir
+        & docker run --rm -it `
+            -v "${hostMount}:/home/runner/work" `
+            -e CI=true `
+            $imageName 'cd /home/runner/work && bash'
+    }
+
+    Default {
+        # 'full'
+        Confirm-DockerImage -Cfg $cfg
+        Write-Host ''
+        Write-Host 'Running full CI simulation...' -ForegroundColor Yellow
+
+        $total = 0
+        if ($cfg.LintCmd)    { $total++ }
+        if ($cfg.CompileCmd) { $total++ }
+        if ($cfg.TestCmd)    { $total++ }
+        if ($ghaggaAvailable) { $total++ }
+
+        $step = 1
+
+        if ($cfg.LintCmd) {
+            Write-Host ''
+            Write-Host "Step $step/$total`: Lint" -ForegroundColor Yellow
+            Write-Host "  $($cfg.LintCmd)" -ForegroundColor Cyan
+            Invoke-InCi -Cfg $cfg -Cmd "cd /home/runner/work && $($cfg.LintCmd)"
+            $step++
+        }
+
+        if ($cfg.CompileCmd) {
+            Write-Host ''
+            Write-Host "Step $step/$total`: Compile" -ForegroundColor Yellow
+            Write-Host "  $($cfg.CompileCmd)" -ForegroundColor Cyan
+            Invoke-InCi -Cfg $cfg -Cmd "cd /home/runner/work && $($cfg.CompileCmd)" -RunUser 'root'
+            $step++
+        }
+
+        if ($cfg.TestCmd) {
+            Write-Host ''
+            Write-Host "Step $step/$total`: Test" -ForegroundColor Yellow
+            Write-Host "  $($cfg.TestCmd)" -ForegroundColor Cyan
+            Invoke-InCi -Cfg $cfg -Cmd "cd /home/runner/work && $($cfg.TestCmd)"
+            $step++
+        }
+
+        if ($ghaggaAvailable) {
+            Write-Host ''
+            Write-Host "Step $step/$total`: GHAGGA Review" -ForegroundColor Yellow
+            Write-Host '  ghagga review --plain --exit-on-issues' -ForegroundColor Cyan
+            & ghagga review --plain --exit-on-issues
+            if ($LASTEXITCODE -ne 0) {
+                Write-Host 'GHAGGA review found issues!' -ForegroundColor Red
+                exit 1
+            }
+        }
+    }
+}
+
+Write-Host ''
+Write-Host 'CI Local completed successfully!' -ForegroundColor Green
+Write-Host '  Safe to push - CI should pass.' -ForegroundColor Green
+Write-Host ''