javi-forge 1.37.1 → 1.38.0

package/README.md

@@ -13,6 +13,10 @@ npx javi-forge init
 
 An interactive TUI guides you through project setup: pick a stack, CI provider, memory module, and get a production-ready project structure in seconds.
 
+## Platform Support
+
+javi-forge 2.0 supports Linux and Windows only. npm package eligibility enforces this boundary. Source or manual execution on every other host returns generic `unsupported-platform` guidance before probes or mutation; there is no legacy-host migration or compatibility mode.
+
 ## What It Creates
 
 `javi-forge init` bootstraps a complete project with 13 sequential steps:
@@ -373,14 +377,10 @@ npx javi-forge doctor
 - **Installed Modules** — engram, obsidian-brain, memory-simple, ghagga
 
 
-## macOS CI-Local support
-
-macOS is deprecated and unsupported for new CI-Local install/startup. Pin a supported release or migrate your workflow. Existing installed guards are not removed in 1.x; Darwin code removal is planned separately for 2.0.
-
 ## Requirements
 
 - **Node.js** >= 22 (required by ink 7; previous versions ran on >= 18)
-- **Linux only** — the `acl` package (provides `getfacl`) is required to install or repair the Claude PreToolUse guard: the transactional installer proves every controlling directory carries no extended ACL, and refuses fail-closed when `getfacl` is unresolvable. Install with `apt install acl`, `apk add acl`, or `dnf install acl` (slim container images usually omit it). An already-installed guard keeps working without it — `javi-forge hooks doctor claude` reports the capability as its own row.
+- **Linux guard installation/repair** — the `acl` package (provides `getfacl`) is required to install or repair the Claude PreToolUse guard: the transactional installer proves every controlling directory carries no endangering ACL, and refuses fail-closed when `getfacl` is unresolvable. Install with `apt install acl`, `apk add acl`, or `dnf install acl` (slim container images usually omit it). An already-installed guard keeps working without it — `javi-forge hooks doctor claude` reports the capability as its own row.
 - **`node` on `PATH`** — Claude Code spawns the guard in exec form, so `node` must resolve on the `PATH` Claude Code itself uses, not only inside javi-forge.
 
 ## Ecosystem

package/assets/claude-hooks/javi-forge-skillguard-pre-tool-use.mjs

@@ -8,7 +8,8 @@ import { fileURLToPath } from "node:url";
 export const MANAGED_MARKER = "// javi-forge-managed: claude-pretooluse v1";
 export const INPUT_LIMIT_BYTES = 1_048_576;
 export const SUPPORTED_TOOLS = Object.freeze(["Bash", "PowerShell", "Read", "Write", "Edit"]);
-export const POLICY_REGISTRY = Object.freeze({ schemaVersion: 1, policyVersion: 1, diagnosticsMaxBytes: 240 });
+export const POLICY_REGISTRY = Object.freeze({ schemaVersion: 1, policyVersion: 2, diagnosticsMaxBytes: 240 });
+export function resolvePlatformSupport(platform = process.platform) { return platform === "linux" || platform === "win32" ? { supported: true } : { supported: false, reason: "unsupported-platform" }; }
 const PROJECT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 // Per-agent adapter config (S0 core-extraction): every agent-specific input the guard needs
 // (the isManaged protected-path set, the project-dir source, the managed marker) is resolved by
@@ -57,7 +58,7 @@ function lexicalNormalize(input, platform) {
 		else parts.push(part);
 	}
 	value = `${root}${root.endsWith("/") || parts.length === 0 ? "" : "/"}${parts.join("/")}`;
-	if (windows || platform === "darwin") value = value.normalize("NFC").toLowerCase();
+	if (windows) value = value.normalize("NFC").toLowerCase();
 	return value;
 }
 function nativeRealpath(input) {
@@ -109,7 +110,7 @@ function policyPathKeys(input, options = {}) {
 function isAbsolutePolicyPath(value) { return POSIX_ABSOLUTE.test(value) || WINDOWS_DRIVE.test(value) || WINDOWS_UNC.test(value) || /^\\(?:\\\?|\?\?|\\\.)\\/i.test(value); }
 // Home-relative credential files, matched as a path SUFFIX (never an expanded
 // literal home) so one rule holds for every user, container and HOME. Literals
-// stay lowercase because lexicalNormalize folds keys on darwin/win32.
+// stay lowercase because lexicalNormalize folds keys on win32.
 const SENSITIVE_PATH_SUFFIXES = Object.freeze(["/.aws/credentials", "/.kube/config", "/.config/gcloud/application_default_credentials.json", "/.docker/config.json", "/.config/gh/hosts.yml"]);
 // Absolute system secrets: the shadow suite holds every local account's password
 // hash, and passwd/vipw leave the "-" backup beside it holding the same secret.
@@ -132,17 +133,16 @@ export function isSensitivePolicyKey(key, platform = process.platform) {
 	if (SENSITIVE_ABSOLUTE_KEYS.includes(key) || PROC_ENVIRON_KEY.test(key)) return true;
 	if (SENSITIVE_PATH_SUFFIXES.some((suffix) => key.endsWith(suffix))) return true;
 	if (SENSITIVE_DIRECTORY_SUFFIXES.some((directory) => key.endsWith(directory) || key.includes(`${directory}/`))) return true;
-	return platform === "win32" || platform === "darwin" ? basename.toLowerCase() === "serviceaccountkey.json" : basename === "serviceAccountKey.json";
+	return platform === "win32" ? basename.toLowerCase() === "serviceaccountkey.json" : basename === "serviceAccountKey.json";
 }
 function isManaged(key, managedSet = CLAUDE_MANAGED_SET, projectRoot = PROJECT_ROOT) {
 	const project = canonicalizePolicyPath(projectRoot);
 	if (!key.startsWith(`${project}/`) && key !== project) return false;
 	const relative = key.slice(project.length + 1);
-	// On case-insensitive platforms lexicalNormalize folds the key to lowercase,
-	// so the mixed-case CLAUDE.md literals must be matched case-insensitively too
-	// (the other literals are already lowercase). Otherwise CLAUDE.md and
-	// .claude/CLAUDE.md lose managed-config protection on macOS/Windows.
-	const foldedClaudeMd = (process.platform === "win32" || process.platform === "darwin") && managedSet.caseFoldExact.includes(relative);
+	// On win32 lexicalNormalize folds the key to lowercase, so the mixed-case
+	// CLAUDE.md literals must be matched case-insensitively too. Otherwise
+	// CLAUDE.md and .claude/CLAUDE.md lose managed-config protection.
+	const foldedClaudeMd = process.platform === "win32" && managedSet.caseFoldExact.includes(relative);
 	return foldedClaudeMd || managedSet.exact.includes(relative) || managedSet.prefixes.some((prefix) => relative.startsWith(prefix));
 }
 function evaluateFile(toolName, filePath, config = AGENT_CONFIGS.claude, projectRoot = PROJECT_ROOT) {
@@ -259,7 +259,7 @@ export function normalizeLiteralUtilityIdentity(rawToken) {
 	// Lexical-only: split on "/" without path/realpath/PATH/alias resolution.
 	// Basename compare is case-insensitive and host-independent so inherited
 	// deny families still fire for CHMOD/ENV/BASE64 on case-insensitive
-	// filesystems, mirroring the darwin/win32 path folding lexicalNormalize
+	// filesystems, mirroring the win32 path folding lexicalNormalize
 	// already applies. The canonical lowercase utility feeds profile lookup.
 	const token = typeof rawToken === "string" ? rawToken : "";
 	const literal = token.length > 0 && !NON_LITERAL_IDENTITY_MARKERS.test(token);
@@ -837,6 +837,7 @@ function diagnostic(error) {
 		"invalid-event": "input does not match the supported event schema",
 		"invalid-config": "missing or unknown --agent selector (expected --agent=<id>)",
 		"oversized-input": "stdin exceeds 1048576 bytes",
+		"unsupported-platform": "Linux and Windows are supported hosts",
 		"missing-policy": "embedded policy registry is unavailable",
 		"internal-error": "policy evaluation could not complete",
 	};
@@ -897,10 +898,11 @@ export function readBoundedStdin(stream = process.stdin) {
 }
 export async function main() {
 	try {
+		if (!resolvePlatformSupport().supported) throw new Error("unsupported-platform");
 		const config = resolveAgentConfig(process.argv);
 		const fault = process.argv.find((arg) => arg.startsWith("--javi-forge-test-fault="))?.split("=")[1];
 		if (fault === "missing-policy") throw new Error("missing-policy");
-		if (POLICY_REGISTRY.schemaVersion !== 1 || POLICY_REGISTRY.policyVersion !== 1) throw new Error("missing-policy");
+		if (POLICY_REGISTRY.schemaVersion !== 1 || POLICY_REGISTRY.policyVersion !== 2) throw new Error("missing-policy");
 		const input = await readBoundedStdin();
 		let parsed;
 		try {

package/assets/claude-hooks/manifest.json

@@ -1 +1,35 @@
-{"schemaVersion":1,"asset":{"name":"javi-forge-skillguard-pre-tool-use.mjs","version":1,"policyVersion":1,"sha256":"9a565cec31d9e091e3fb9420b86685f824733bc1ebe479f086b2b955aba6ef3e","historical":["78be7e6613c012280b7ad17886462ba166b63ebd031e34565d757b3a0796d7cc","5dc2a5c31131f4ac7d8657c78b950de52776aad6eaefe78ea0d764a9963c4425","0c9aa8fa26b389f4892782f83104f0792c2b71ebca39c18c02706e2185e22b40","3581862f0567cce75a58b693c9ade80d39ee7d58add11537a34a8461c47c1ed4","54a270f28b068450b79547a88ec6f2d4854514392fd5f38ed1d6174ea093d7aa"]},"settingsEntries":{"current":{"version":1,"canonicalSha256":"b1341803cd076091edfcb473494514df1a23bd33372374ca1de6b75258e52e06"},"historical":[{"version":1,"canonicalSha256":"038c59a91bf8967f6908afed74c465f1e7030254e11e4f8738975d6d708424d4"}]},"installerHelpers":{"windowsSecureObject":{"name":"javi-forge-windows-secure-object.ps1","sha256":"2289ef6ac6b039ec74dc3ea0894413e243ff9bea963f04008a356b3838f9b8dd"}}}
+{
+	"schemaVersion": 1,
+	"asset": {
+		"name": "javi-forge-skillguard-pre-tool-use.mjs",
+		"version": 1,
+		"policyVersion": 2,
+		"sha256": "59fc4224975ad64cfc85bab50ec60d9bd4948070e9d41f42ab43e6d8231c19a1",
+		"historical": [
+			"78be7e6613c012280b7ad17886462ba166b63ebd031e34565d757b3a0796d7cc",
+			"5dc2a5c31131f4ac7d8657c78b950de52776aad6eaefe78ea0d764a9963c4425",
+			"0c9aa8fa26b389f4892782f83104f0792c2b71ebca39c18c02706e2185e22b40",
+			"3581862f0567cce75a58b693c9ade80d39ee7d58add11537a34a8461c47c1ed4",
+			"54a270f28b068450b79547a88ec6f2d4854514392fd5f38ed1d6174ea093d7aa",
+			"9a565cec31d9e091e3fb9420b86685f824733bc1ebe479f086b2b955aba6ef3e"
+		]
+	},
+	"settingsEntries": {
+		"current": {
+			"version": 1,
+			"canonicalSha256": "b1341803cd076091edfcb473494514df1a23bd33372374ca1de6b75258e52e06"
+		},
+		"historical": [
+			{
+				"version": 1,
+				"canonicalSha256": "038c59a91bf8967f6908afed74c465f1e7030254e11e4f8738975d6d708424d4"
+			}
+		]
+	},
+	"installerHelpers": {
+		"windowsSecureObject": {
+			"name": "javi-forge-windows-secure-object.ps1",
+			"sha256": "2289ef6ac6b039ec74dc3ea0894413e243ff9bea963f04008a356b3838f9b8dd"
+		}
+	}
+}

package/ci-local/README.md

@@ -39,21 +39,18 @@ cd /path/to/new-project
 .\.ci-local\install.ps1     # Windows (PowerShell 7+)
 ```
 
-> **Importante:** CI-Local depende de `lib/common.sh` (Linux/WSL) y/o `lib/common.psm1` (Windows). Copiá ambos junto con el directorio `ci-local/`. macOS está deprecated y se rechaza para instalaciones o arranques nuevos.
+> **Importante:** CI-Local depende de `lib/common.sh` (Linux/WSL) 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.
 
 
-## macOS deprecation
+## Plataformas compatibles
 
-macOS is deprecated and unsupported for new CI-Local install/startup. Pin a supported release or migrate your workflow. Existing installed guards are not removed in 1.x; Darwin code removal is planned separately for 2.0.
-
-### Soporte cross-platform
+CI-Local soporta Linux/WSL y Windows nativo. Cualquier otro host recibe `unsupported-platform` antes de ejecutar comandos, probes, instalación o mutaciones. No existe un modo de compatibilidad ni un flujo de migración para hosts no soportados.
 
 | Plataforma | Installer | Runner | Hooks | Requisitos |
 |---|---|---|---|---|
 | Linux | `install.sh` | `ci-local.sh` | bash | bash, perl, docker (opcional) |
-| macOS | Unsupported: pin a supported release or migrate | Refused before startup | Existing installed guards retained | No new install or startup |
 | 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) |
 

package/ci-local/ci-local.ps1

@@ -27,8 +27,8 @@ function Invoke-CiLocalMain {
         [ref]$ExitCode
     )
 
-    if ($Platform -eq 'Darwin') {
-        Write-Host 'macOS is deprecated and unsupported for new CI-Local install/startup. Pin a supported release or migrate. Existing installed guards are not removed; Darwin code removal is planned separately for 2.0.'
+    if ($Platform -notin @('Linux', 'Windows')) {
+        Write-Host 'unsupported-platform: javi-forge supports Linux and Windows only.'
         if ($PSBoundParameters.ContainsKey('ExitCode')) {
             $ExitCode.Value = 1
             return
@@ -36,15 +36,22 @@ function Invoke-CiLocalMain {
         return 1
     }
 
-    Invoke-CiLocalStartupBody -Platform $Platform
+    $bodyExitCode = 0
+    & ${function:Invoke-CiLocalStartupBody} -Platform $Platform -ExitCode ([ref]$bodyExitCode)
     if ($PSBoundParameters.ContainsKey('ExitCode')) {
-        $ExitCode.Value = 0
+        $ExitCode.Value = $bodyExitCode
+    } elseif ($bodyExitCode -ne 0) {
+        return $bodyExitCode
     }
 }
 
 function Invoke-CiLocalStartupBody {
-    param([string]$Platform)
+    param(
+        [string]$Platform,
+        [ref]$ExitCode
+    )
 
+    $ExitCode.Value = 0
 # 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
@@ -291,12 +298,15 @@ function Confirm-DockerImage {
             $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' }
+        if ($LASTEXITCODE -ne 0) {
+            $ExitCode.Value = $LASTEXITCODE
+            return
+        }
     }
 }
 
 # Convert a host path to the form expected by docker run -v.
-# Linux/macOS:  /path/to/x         -> /path/to/x  (pass through)
+# Linux/WSL:    /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 {
@@ -348,7 +358,10 @@ function Invoke-InCi {
         -v "${hostMount}:/home/runner/work" `
         -e CI=true `
         $imageName timeout $timeout bash -c $Cmd
-    if ($LASTEXITCODE -ne 0) { throw "step failed with exit $LASTEXITCODE" }
+    if ($LASTEXITCODE -ne 0) {
+        $ExitCode.Value = $LASTEXITCODE
+        return
+    }
 }
 
 # ─── Main ─────────────────────────────────────────────────────────────
@@ -385,21 +398,25 @@ switch ($Mode) {
 
     'quick' {
         Confirm-DockerImage -Cfg $cfg
+        if ($ExitCode.Value -ne 0) { return }
         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 ($ExitCode.Value -ne 0) { return }
         }
         if ($cfg.CompileCmd) {
             Write-Host "Compile: $($cfg.CompileCmd)" -ForegroundColor Cyan
             Invoke-InCi -Cfg $cfg -Cmd "cd /home/runner/work && $($cfg.CompileCmd)" -RunUser 'root'
+            if ($ExitCode.Value -ne 0) { return }
         }
     }
 
     'shell' {
         Confirm-DockerImage -Cfg $cfg
+        if ($ExitCode.Value -ne 0) { return }
         Write-Host ''
         Write-Host 'Opening shell in CI environment...' -ForegroundColor Yellow
         $imageName = Get-ImageName -StackType $cfg.StackType
@@ -408,11 +425,16 @@ switch ($Mode) {
             -v "${hostMount}:/home/runner/work" `
             -e CI=true `
             $imageName 'cd /home/runner/work && bash'
+        if ($LASTEXITCODE -ne 0) {
+            $ExitCode.Value = $LASTEXITCODE
+            return
+        }
     }
 
     Default {
         # 'full'
         Confirm-DockerImage -Cfg $cfg
+        if ($ExitCode.Value -ne 0) { return }
         Write-Host ''
         Write-Host 'Running full CI simulation...' -ForegroundColor Yellow
 
@@ -429,6 +451,7 @@ switch ($Mode) {
             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)"
+            if ($ExitCode.Value -ne 0) { return }
             $step++
         }
 
@@ -437,6 +460,7 @@ switch ($Mode) {
             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'
+            if ($ExitCode.Value -ne 0) { return }
             $step++
         }
 
@@ -445,6 +469,7 @@ switch ($Mode) {
             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)"
+            if ($ExitCode.Value -ne 0) { return }
             $step++
         }
 
@@ -455,7 +480,8 @@ switch ($Mode) {
             & ghagga review --plain --exit-on-issues
             if ($LASTEXITCODE -ne 0) {
                 Write-Host 'GHAGGA review found issues!' -ForegroundColor Red
-                exit 1
+                $ExitCode.Value = $LASTEXITCODE
+                return
             }
         }
     }
@@ -468,7 +494,7 @@ Write-Host ''
 }
 
 if ($MyInvocation.InvocationName -ne '.') {
-    $platform = if ($IsMacOS) { 'Darwin' } else { 'Windows' }
+    $platform = if ($IsWindows) { 'Windows' } elseif ($IsLinux) { 'Linux' } else { 'unsupported' }
     $exitCode = 0
     & ${function:Invoke-CiLocalMain} -Platform $platform -ExitCode ([ref]$exitCode)
     if ($exitCode -ne 0) {

package/ci-local/ci-local.sh

@@ -11,23 +11,40 @@
 #   ./ci-local.sh detect       # Mostrar stack detectado
 # =============================================================================
 
-function ci_local_main() {
+
+CI_LOCAL_ENTRYPOINT_SOURCE="${BASH_SOURCE[0]}"
+if [[ "$CI_LOCAL_ENTRYPOINT_SOURCE" == /* ]]; then
+    CI_LOCAL_ENTRYPOINT_PATH="$CI_LOCAL_ENTRYPOINT_SOURCE"
+else
+    CI_LOCAL_ENTRYPOINT_PATH="$PWD/$CI_LOCAL_ENTRYPOINT_SOURCE"
+fi
+CI_LOCAL_ENTRYPOINT_DIR="${CI_LOCAL_ENTRYPOINT_PATH%/*}"
+
+function ci_local_normalize_platform() {
     local platform="${1:?platform required}"
-    shift
 
-    if [ "$platform" = "Darwin" ]; then
-        printf '%s\n' 'macOS is deprecated and unsupported for new CI-Local install/startup. Pin a supported release or migrate. Existing installed guards are not removed; Darwin code removal is planned separately for 2.0.'
-        return 1
-    fi
+    case "$platform" in
+        MINGW*_NT-*|MSYS*|CYGWIN*) printf '%s\n' 'Windows' ;;
+        *) printf '%s\n' "$platform" ;;
+    esac
+}
+
+function ci_local_main() {
+    local platform
+    platform="$(ci_local_normalize_platform "${1:?platform required}")"
+    shift
 
-    ci_local_startup_body "$@"
+    case "$platform" in
+        Linux|Windows) ci_local_startup_body "$@" ;;
+        *) printf '%s\n' 'unsupported-platform: javi-forge supports Linux and Windows only.'; return 1 ;;
+    esac
 }
 
 function ci_local_startup_body() {
     set -e
 
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+SCRIPT_DIR="$CI_LOCAL_ENTRYPOINT_DIR"
+PROJECT_DIR="${SCRIPT_DIR%/*}"
 
 # Require realpath: load-bearing for the lib symlink check below.
 if ! command -v realpath >/dev/null 2>&1; then

package/ci-local/install.ps1

@@ -7,7 +7,7 @@
 #   .\install.ps1
 #
 # Behaviour MUST match install.sh. Diff against the bash version on every
-# change. Test on real Windows + WSL + macOS pwsh before tagging a release.
+# change. Test on supported Windows and WSL hosts before tagging a release.
 # =============================================================================
 
 #Requires -Version 7.2
@@ -15,19 +15,36 @@
 param()
 
 function Invoke-CiLocalMain {
-    param([Parameter(Mandatory)][string]$Platform)
-
-    if ($Platform -eq 'Darwin') {
-        Write-Host 'macOS is deprecated and unsupported for new CI-Local install/startup. Pin a supported release or migrate. Existing installed guards are not removed; Darwin code removal is planned separately for 2.0.'
+    param(
+        [Parameter(Mandatory)][string]$Platform,
+        [ref]$ExitCode
+    )
+
+    if ($Platform -notin @('Linux', 'Windows')) {
+        Write-Host 'unsupported-platform: javi-forge supports Linux and Windows only.'
+        if ($PSBoundParameters.ContainsKey('ExitCode')) {
+            $ExitCode.Value = 1
+            return
+        }
         return 1
     }
 
-    Invoke-CiLocalStartupBody -Platform $Platform
+    $bodyExitCode = 0
+    & ${function:Invoke-CiLocalStartupBody} -Platform $Platform -ExitCode ([ref]$bodyExitCode)
+    if ($PSBoundParameters.ContainsKey('ExitCode')) {
+        $ExitCode.Value = $bodyExitCode
+    } elseif ($bodyExitCode -ne 0) {
+        return $bodyExitCode
+    }
 }
 
 function Invoke-CiLocalStartupBody {
-    param([string]$Platform)
+    param(
+        [string]$Platform,
+        [ref]$ExitCode
+    )
 
+    $ExitCode.Value = 0
 # Defense-in-depth: #Requires is parsed by some hosts AFTER the script body.
 # 7.2 is the minimum because FileSystemInfo.ResolveLinkTarget($true) is .NET 6+,
 # which shipped with pwsh 7.2. Earlier pwsh 7.x runs on .NET 5 and the method
@@ -159,9 +176,11 @@ try {
 
     $jfVersionOk     = $true
     $jfVersionOutput = ''
+    $jfVersionExitCode = 1
     try {
         $jfVersionOutput = (& javi-forge --version 2>&1) -join "`n"
-        if ($LASTEXITCODE -ne 0) { $jfVersionOk = $false }
+        $jfVersionExitCode = $LASTEXITCODE
+        if ($jfVersionExitCode -ne 0) { $jfVersionOk = $false }
     } catch {
         $jfVersionOk     = $false
         $jfVersionOutput = $_.Exception.Message
@@ -177,7 +196,8 @@ try {
         Write-Host "ERROR: javi-forge found at $jfPath but '--version' failed" -ForegroundColor Red
         Write-Host "Output: $jfVersionOutput" -ForegroundColor Yellow
         Write-Host 'Reinstall: npm install -g javi-forge' -ForegroundColor Cyan
-        exit 1
+        $ExitCode.Value = $jfVersionExitCode
+        return
     }
 
     # Reject UNC / remote paths outright — a javi-forge symlinked to
@@ -297,12 +317,13 @@ try {
     & git config core.hooksPath $hooksRel
     if ($LASTEXITCODE -ne 0) {
         Write-Host 'ERROR: failed to set core.hooksPath. Are you inside a git repo?' -ForegroundColor Red
-        exit 1
+        $ExitCode.Value = $LASTEXITCODE
+        return
     }
     Write-Host "hooksPath = $hooksRel" -ForegroundColor Green
 
     # Make hooks executable. Different OS, different model:
-    #   - macOS / Linux / WSL: chmod 0755 — POSIX bits, what git expects.
+    #   - Linux / WSL: chmod 0755 — POSIX bits, what git expects.
     #   - Windows native NTFS: chmod is a no-op; lock the ACL via icacls so
     #     only the current user can rewrite the hooks between commits.
     if (Test-CommandExists -Name 'chmod') {
@@ -382,9 +403,10 @@ try {
 }
 
 if ($MyInvocation.InvocationName -ne '.') {
-    $platform = if ($IsMacOS) { 'Darwin' } else { 'Windows' }
-    $exitCode = & ${function:Invoke-CiLocalMain} -Platform $platform
-    if ($exitCode -is [int] -and $exitCode -ne 0) {
+    $platform = if ($IsWindows) { 'Windows' } elseif ($IsLinux) { 'Linux' } else { 'unsupported' }
+    $exitCode = 0
+    & ${function:Invoke-CiLocalMain} -Platform $platform -ExitCode ([ref]$exitCode)
+    if ($exitCode -ne 0) {
         exit $exitCode
     }
 }

package/ci-local/install.sh

@@ -3,22 +3,40 @@
 # CI-LOCAL: Installation Script
 # =============================================================================
 
-function ci_local_main() {
+
+CI_LOCAL_ENTRYPOINT_SOURCE="${BASH_SOURCE[0]}"
+if [[ "$CI_LOCAL_ENTRYPOINT_SOURCE" == /* ]]; then
+    CI_LOCAL_ENTRYPOINT_PATH="$CI_LOCAL_ENTRYPOINT_SOURCE"
+else
+    CI_LOCAL_ENTRYPOINT_PATH="$PWD/$CI_LOCAL_ENTRYPOINT_SOURCE"
+fi
+CI_LOCAL_ENTRYPOINT_DIR="${CI_LOCAL_ENTRYPOINT_PATH%/*}"
+
+function ci_local_normalize_platform() {
     local platform="${1:?platform required}"
 
-    if [ "$platform" = "Darwin" ]; then
-        printf '%s\n' 'macOS is deprecated and unsupported for new CI-Local install/startup. Pin a supported release or migrate. Existing installed guards are not removed; Darwin code removal is planned separately for 2.0.'
-        return 1
-    fi
+    case "$platform" in
+        MINGW*_NT-*|MSYS*|CYGWIN*) printf '%s\n' 'Windows' ;;
+        *) printf '%s\n' "$platform" ;;
+    esac
+}
 
-    ci_local_startup_body "$platform"
+function ci_local_main() {
+    local platform
+    platform="$(ci_local_normalize_platform "${1:?platform required}")"
+    shift
+
+    case "$platform" in
+        Linux|Windows) ci_local_startup_body "$@" ;;
+        *) printf '%s\n' 'unsupported-platform: javi-forge supports Linux and Windows only.'; return 1 ;;
+    esac
 }
 
 function ci_local_startup_body() {
     set -e
 
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+SCRIPT_DIR="$CI_LOCAL_ENTRYPOINT_DIR"
+PROJECT_DIR="${SCRIPT_DIR%/*}"
 
 # ─── Required tools (fail-closed) ──────────────────────────────────
 # realpath is load-bearing for the symlink-traversal checks below. If it's
@@ -27,7 +45,6 @@ PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
 if ! command -v realpath >/dev/null 2>&1; then
     printf 'ERROR: realpath is required for ci-local install (symlink checks).\n' >&2
     printf '  Linux/WSL: install coreutils\n' >&2
-    printf '  macOS:     brew install coreutils, then add gnubin to PATH\n' >&2
     exit 1
 fi
 
@@ -208,5 +225,5 @@ echo -e ""
 }
 
 if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
-    ci_local_main "$(/usr/bin/uname -s)"
+    ci_local_main "$(/usr/bin/uname -s)" "$@"
 fi

package/ci-local/lib/common.sh

@@ -39,16 +39,12 @@ log_info() { echo -e "  ${CYAN}[INFO]${NC} $1"; }
 log_step() { echo -e "${YELLOW}$1${NC}"; }
 
 # =============================================================================
-# sed_inplace - Portable sed -i (works on both GNU and BSD/macOS sed)
+# sed_inplace - GNU sed -i for supported Linux/WSL hosts
 # =============================================================================
 # Usage: sed_inplace "s/foo/bar/" file.txt
 # =============================================================================
 sed_inplace() {
-    if sed --version 2>/dev/null | grep -q GNU; then
-        sed -i "$@"
-    else
-        sed -i '' "$@"
-    fi
+    sed -i "$@"
 }
 
 # =============================================================================
@@ -100,7 +96,7 @@ detect_stack() {
         STACK_TYPE="java-gradle"
         BUILD_TOOL="gradle"
 
-        # Detect Java version from build files (compatible with macOS and Linux)
+        # Detect Java version from build files
         if [[ -f "$project_dir/build.gradle.kts" ]]; then
             JAVA_VERSION=$(grep -E 'languageVersion\s*=\s*JavaLanguageVersion\.of\(' "$project_dir/build.gradle.kts" 2>/dev/null | grep -o '[0-9]\+' | head -1 || echo "21")
         elif [[ -f "$project_dir/build.gradle" ]]; then

package/ci-local/uninstall.ps1

@@ -16,6 +16,42 @@ param(
     [switch]$Purge
 )
 
+
+function Invoke-CiLocalMain {
+    param(
+        [Parameter(Mandatory)][string]$Platform,
+        [switch]$RestoreBackups,
+        [switch]$Purge,
+        [ref]$ExitCode
+    )
+
+    if ($Platform -notin @('Linux', 'Windows')) {
+        Write-Host 'unsupported-platform: javi-forge supports Linux and Windows only.'
+        if ($PSBoundParameters.ContainsKey('ExitCode')) {
+            $ExitCode.Value = 1
+            return
+        }
+        return 1
+    }
+
+    $bodyExitCode = 0
+    & ${function:Invoke-CiLocalStartupBody} -Platform $Platform -RestoreBackups:$RestoreBackups -Purge:$Purge -ExitCode ([ref]$bodyExitCode)
+    if ($PSBoundParameters.ContainsKey('ExitCode')) {
+        $ExitCode.Value = $bodyExitCode
+    } elseif ($bodyExitCode -ne 0) {
+        return $bodyExitCode
+    }
+}
+
+function Invoke-CiLocalStartupBody {
+    param(
+        [Parameter(Mandatory)][string]$Platform,
+        [switch]$RestoreBackups,
+        [switch]$Purge,
+        [ref]$ExitCode
+    )
+
+$ExitCode.Value = 0
 Set-StrictMode -Version Latest
 $ErrorActionPreference = 'Stop'
 
@@ -32,6 +68,10 @@ try {
     $current = (& git config --get core.hooksPath 2>$null) -join ''
     if ($current) {
         & git config --unset core.hooksPath
+        if ($LASTEXITCODE -ne 0) {
+            $ExitCode.Value = $LASTEXITCODE
+            return
+        }
         Write-Host "Removed hooksPath = $current" -ForegroundColor Green
     } else {
         Write-Host 'No core.hooksPath was set; nothing to remove' -ForegroundColor Yellow
@@ -83,3 +123,13 @@ try {
 } finally {
     Pop-Location
 }
+}
+
+if ($MyInvocation.InvocationName -ne '.') {
+    $platform = if ($IsWindows) { 'Windows' } elseif ($IsLinux) { 'Linux' } else { 'unsupported' }
+    $exitCode = 0
+    & ${function:Invoke-CiLocalMain} -Platform $platform -RestoreBackups:$RestoreBackups -Purge:$Purge -ExitCode ([ref]$exitCode)
+    if ($exitCode -ne 0) {
+        exit $exitCode
+    }
+}