javi-forge 1.37.0 → 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/assets/hooks/manifest.json

@@ -14,8 +14,8 @@
 		]
 	},
 	"pre-push": {
-		"version": 3,
-		"sha256": "c396387a15c3c448d524f68597a993f6b4341ae06143d2d5907ad914823d0ad0",
+		"version": 4,
+		"sha256": "ffe1b5dd0931617df3c9fea37947dac84dffd11c490c39590459e861b404148d",
 		"historical": [
 			{
 				"sha256": "7de58640aeef33085a49f31f1d9d0c8bacde0069d6d3265ae41aa8d3cd14d7a5",
@@ -28,6 +28,10 @@
 			{
 				"sha256": "c396387a15c3c448d524f68597a993f6b4341ae06143d2d5907ad914823d0ad0",
 				"firstCommit": "0779d746b23ad614a13181d60f1fe3aa034e91dd"
+			},
+			{
+				"sha256": "ffe1b5dd0931617df3c9fea37947dac84dffd11c490c39590459e861b404148d",
+				"firstCommit": "6b5799d9d9e8c528fad9dc1f7b641afbd3a60637"
 			}
 		]
 	},

package/assets/hooks/pre-push

@@ -4,13 +4,211 @@
 # Default: quick native CI gate (setup + lint + compile + gates — no tests, no coverage).
 # Requires javi-forge on PATH (npx fallback; offline npx fails -> hook fails closed).
 # To skip: git push --no-verify
-set -e
-if command -v javi-forge >/dev/null 2>&1; then
-  javi-forge hooks run pre-push
-else
-  npx javi-forge hooks run pre-push
-fi || {
+fail_pre_push() {
+  message=$1
+  status=${2:-1}
   echo ""
-  echo "pre-push FAILED - fix the issues above."
-  exit 1
+  echo "pre-push FAILED - $message"
+  exit "$status"
+}
+
+hash_required_file() {
+  target=$1
+  if [ -L "$target" ] || [ ! -f "$target" ]; then
+    return 1
+  fi
+  git hash-object --no-filters "$target"
+}
+
+hash_optional_file() {
+  target=$1
+  if [ -L "$target" ]; then
+    return 1
+  fi
+  if [ -f "$target" ]; then
+    git hash-object --no-filters "$target"
+    return $?
+  fi
+  if [ -e "$target" ]; then
+    return 1
+  fi
+  printf '%s\n' absent
 }
+
+# Git exports repository-local targeting variables to hooks. Preserve every
+# path needed for this repository before clearing the complete Git-owned set.
+if ! repository_root=$(git rev-parse --show-toplevel) || [ -z "$repository_root" ]; then
+  fail_pre_push "Could not resolve the repository root."
+fi
+if ! cd "$repository_root"; then
+  fail_pre_push "Could not return to the repository root."
+fi
+if ! git_dir=$(git rev-parse --absolute-git-dir) || [ -z "$git_dir" ]; then
+  fail_pre_push "Could not resolve the worktree Git directory."
+fi
+if ! common_dir=$(git rev-parse --path-format=absolute --git-common-dir) || [ -z "$common_dir" ]; then
+  fail_pre_push "Could not resolve the common Git directory."
+fi
+if ! index_path=$(git rev-parse --path-format=absolute --git-path index) || [ -z "$index_path" ]; then
+  fail_pre_push "Could not resolve the worktree index."
+fi
+if ! worktree_config_path=$(git rev-parse --path-format=absolute --git-path config.worktree) || [ -z "$worktree_config_path" ]; then
+  fail_pre_push "Could not resolve the worktree-local Git config."
+fi
+
+if ! git_local_env_vars=$(git rev-parse --local-env-vars); then
+  fail_pre_push "Could not discover Git-local environment variables."
+fi
+
+git_local_env_count=0
+invalid_git_local_env_var=
+saved_ifs=$IFS
+IFS='
+'
+for git_local_env_var in $git_local_env_vars; do
+  git_local_env_count=$((git_local_env_count + 1))
+  case "$git_local_env_var" in
+    GIT_*) ;;
+    *) invalid_git_local_env_var=$git_local_env_var ;;
+  esac
+  case "$git_local_env_var" in
+    *[!A-Za-z0-9_]*) invalid_git_local_env_var=$git_local_env_var ;;
+  esac
+  if [ -n "$invalid_git_local_env_var" ]; then
+    break
+  fi
+done
+IFS=$saved_ifs
+
+if [ "$git_local_env_count" -eq 0 ]; then
+  fail_pre_push "Git returned no Git-local environment variables."
+fi
+if [ -n "$invalid_git_local_env_var" ]; then
+  fail_pre_push "Invalid Git-local environment variable name: $invalid_git_local_env_var"
+fi
+
+# A bounded canary protects the metadata proven vulnerable in the incident.
+common_config_path="$common_dir/config"
+head_path="$git_dir/HEAD"
+packed_refs_path="$common_dir/packed-refs"
+
+if ! common_config_before=$(hash_required_file "$common_config_path"); then
+  fail_pre_push "Could not snapshot the common Git config."
+fi
+if ! head_before=$(hash_required_file "$head_path"); then
+  fail_pre_push "Could not snapshot HEAD."
+fi
+if ! index_before=$(hash_required_file "$index_path"); then
+  fail_pre_push "Could not snapshot the worktree index."
+fi
+if ! worktree_config_before=$(hash_optional_file "$worktree_config_path"); then
+  fail_pre_push "Could not snapshot the worktree-local Git config."
+fi
+if ! packed_refs_before=$(hash_optional_file "$packed_refs_path"); then
+  fail_pre_push "Could not snapshot packed refs."
+fi
+
+attached_ref=
+ref_path=
+ref_before=detached
+if attached_ref=$(git symbolic-ref -q HEAD); then
+  if ! ref_path=$(git rev-parse --path-format=absolute --git-path "$attached_ref") || [ -z "$ref_path" ]; then
+    fail_pre_push "Could not resolve the attached HEAD ref."
+  fi
+  if ! ref_before=$(hash_optional_file "$ref_path"); then
+    fail_pre_push "Could not snapshot the attached HEAD ref."
+  fi
+  if ! ref_oid_before=$(git rev-parse --verify "$attached_ref"); then
+    fail_pre_push "Could not resolve the attached HEAD ref value."
+  fi
+else
+  symbolic_ref_status=$?
+  if [ "$symbolic_ref_status" -ne 1 ]; then
+    fail_pre_push "Could not determine whether HEAD is attached."
+  fi
+  if ! ref_oid_before=$(git rev-parse --verify HEAD); then
+    fail_pre_push "Could not resolve detached HEAD."
+  fi
+fi
+
+# The scrub lives in a subshell: the hook retains its own targeting context for
+# the post-test canary, while the dispatcher and every descendant start clean.
+if (
+  scrub_ifs=$IFS
+  IFS='
+'
+  for git_local_env_var in $git_local_env_vars; do
+    if ! unset "$git_local_env_var"; then
+      echo "pre-push: could not unset $git_local_env_var"
+      exit 1
+    fi
+    if declare -p "$git_local_env_var" >/dev/null 2>&1; then
+      echo "pre-push: $git_local_env_var remained set after unset"
+      exit 1
+    fi
+  done
+  IFS=$scrub_ifs
+
+  if ! cd "$repository_root"; then
+    echo "pre-push: could not return to the repository root after scrubbing"
+    exit 1
+  fi
+
+  if command -v javi-forge >/dev/null 2>&1; then
+    javi-forge hooks run pre-push
+  else
+    npx javi-forge hooks run pre-push
+  fi
+); then
+  test_status=0
+else
+  test_status=$?
+fi
+
+if ! cd "$repository_root"; then
+  fail_pre_push "Could not return to the repository root after tests."
+fi
+
+if ! common_config_after=$(hash_required_file "$common_config_path"); then
+  fail_pre_push "Could not verify the common Git config after tests."
+fi
+if ! head_after=$(hash_required_file "$head_path"); then
+  fail_pre_push "Could not verify HEAD after tests."
+fi
+if ! index_after=$(hash_required_file "$index_path"); then
+  fail_pre_push "Could not verify the worktree index after tests."
+fi
+if ! worktree_config_after=$(hash_optional_file "$worktree_config_path"); then
+  fail_pre_push "Could not verify the worktree-local Git config after tests."
+fi
+if ! packed_refs_after=$(hash_optional_file "$packed_refs_path"); then
+  fail_pre_push "Could not verify packed refs after tests."
+fi
+
+ref_after=detached
+if [ -n "$attached_ref" ]; then
+  if ! ref_after=$(hash_optional_file "$ref_path"); then
+    fail_pre_push "Could not verify the attached HEAD ref after tests."
+  fi
+  if ! ref_oid_after=$(git rev-parse --verify "$attached_ref"); then
+    fail_pre_push "Could not resolve the attached HEAD ref value after tests."
+  fi
+else
+  if ! ref_oid_after=$(git rev-parse --verify HEAD); then
+    fail_pre_push "Could not resolve detached HEAD after tests."
+  fi
+fi
+
+if [ "$common_config_before" != "$common_config_after" ] ||
+  [ "$head_before" != "$head_after" ] ||
+  [ "$index_before" != "$index_after" ] ||
+  [ "$worktree_config_before" != "$worktree_config_after" ] ||
+  [ "$packed_refs_before" != "$packed_refs_after" ] ||
+  [ "$ref_before" != "$ref_after" ] ||
+  [ "$ref_oid_before" != "$ref_oid_after" ]; then
+  fail_pre_push "Git metadata changed during pre-push tests."
+fi
+
+if [ "$test_status" -ne 0 ]; then
+  fail_pre_push "fix the issues above." "$test_status"
+fi

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