arkaos 2.10.1 → 2.12.0

package/VERSION

@@ -1 +1 @@
-2.10.1
+2.12.0

package/config/hooks/cwd-changed.ps1

@@ -0,0 +1,144 @@
+# ============================================================================
+# ArkaOS — CwdChanged Hook (Windows / PowerShell 5.1+)
+#
+# Port of config/hooks/cwd-changed.sh. Fires when the working directory
+# changes. Detects ecosystem and stack so Claude knows which squad and
+# tooling apply to the project.
+#
+# Contract:
+# - Reads a JSON object on stdin with a `cwd` field.
+# - Emits `{"additionalContext": "..."}` on stdout when context is found,
+#   or nothing (and exit 0) when there is nothing to say.
+# ============================================================================
+
+$ErrorActionPreference = 'Stop'
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+
+# ─── Read hook payload from stdin (with empty-stdin fallback) ─────────
+# On Claude Code Windows v2.1.97 the hook pipe is opened but the parent
+# writes zero bytes before closing — every hook gets empty stdin on
+# Windows. Instead of silent-exiting, fall back to `$env:CLAUDE_PROJECT_DIR`
+# (the one env var CC Windows does set on hook invocations) and run the
+# normal ecosystem / stack detection against it. This means a Windows
+# user who `cd`s into a different project inside Claude Code still gets
+# the [arka:project-context] line based on the project root CC knows
+# about, even with the stdin delivery bug.
+$stdinText = [Console]::In.ReadToEnd()
+$newCwd = $null
+
+if (-not [string]::IsNullOrWhiteSpace($stdinText)) {
+    try {
+        $payload = $stdinText | ConvertFrom-Json
+        if ($payload.cwd) { $newCwd = [string]$payload.cwd }
+    } catch {
+        # Malformed payload — fall through to the env-var fallback.
+    }
+}
+
+if ([string]::IsNullOrWhiteSpace($newCwd) -and $env:CLAUDE_PROJECT_DIR) {
+    $newCwd = $env:CLAUDE_PROJECT_DIR
+}
+
+if ([string]::IsNullOrWhiteSpace($newCwd)) { exit 0 }
+if (-not (Test-Path -LiteralPath $newCwd -PathType Container)) { exit 0 }
+
+# ─── Detect ecosystem from ecosystems.json ─────────────────────────────
+$ecosystemsFile = Join-Path $env:USERPROFILE '.claude\skills\arka\knowledge\ecosystems.json'
+$ecosystem = ''
+$ecosystemName = ''
+
+if (Test-Path -LiteralPath $ecosystemsFile) {
+    try {
+        $eco = Get-Content -Raw -LiteralPath $ecosystemsFile -Encoding UTF8 | ConvertFrom-Json
+        if ($eco.ecosystems) {
+            # Pass 1: substring match of any project name in the cwd path.
+            foreach ($ecoProp in $eco.ecosystems.PSObject.Properties) {
+                $ecoId = $ecoProp.Name
+                $ecoObj = $ecoProp.Value
+                $projects = @($ecoObj.projects)
+                foreach ($proj in $projects) {
+                    if ($proj -and $newCwd.Contains([string]$proj)) {
+                        $ecosystem = $ecoId
+                        $ecosystemName = if ($ecoObj.name) { [string]$ecoObj.name } else { $ecoId }
+                        break
+                    }
+                }
+                if ($ecosystem) { break }
+            }
+
+            # Pass 2: if the path looks Herd-hosted, match by directory basename.
+            if (-not $ecosystem -and $newCwd -match 'herd') {
+                $dirName = Split-Path -Leaf $newCwd.TrimEnd('\','/')
+                foreach ($ecoProp in $eco.ecosystems.PSObject.Properties) {
+                    $ecoId = $ecoProp.Name
+                    $ecoObj = $ecoProp.Value
+                    $projects = @($ecoObj.projects)
+                    foreach ($proj in $projects) {
+                        if ($proj -eq $dirName) {
+                            $ecosystem = $ecoId
+                            $ecosystemName = if ($ecoObj.name) { [string]$ecoObj.name } else { $ecoId }
+                            break
+                        }
+                    }
+                    if ($ecosystem) { break }
+                }
+            }
+        }
+    } catch {
+        # Malformed ecosystems.json — degrade gracefully.
+    }
+}
+
+# ─── Detect stack ──────────────────────────────────────────────────────
+$stack = 'unknown'
+
+$composerJson  = Join-Path $newCwd 'composer.json'
+$packageJson   = Join-Path $newCwd 'package.json'
+$pyprojectToml = Join-Path $newCwd 'pyproject.toml'
+
+if (Test-Path -LiteralPath $composerJson) {
+    $stack = 'laravel'
+} elseif (Test-Path -LiteralPath $packageJson) {
+    try {
+        $pkgText = Get-Content -Raw -LiteralPath $packageJson -Encoding UTF8
+        if     ($pkgText -like '*"nuxt"*')  { $stack = 'nuxt' }
+        elseif ($pkgText -like '*"next"*')  { $stack = 'nextjs' }
+        elseif ($pkgText -like '*"react"*') { $stack = 'react' }
+        elseif ($pkgText -like '*"vue"*')   { $stack = 'vue' }
+        else                                 { $stack = 'node' }
+    } catch {
+        $stack = 'node'
+    }
+} elseif (Test-Path -LiteralPath $pyprojectToml) {
+    $stack = 'python'
+}
+
+# ─── Check for project descriptor ─────────────────────────────────────
+$dirName = Split-Path -Leaf $newCwd.TrimEnd('\','/')
+$projectsDir   = Join-Path $env:USERPROFILE '.claude\skills\arka\projects'
+$descriptorFile = Join-Path $projectsDir "$dirName.md"
+$descriptorDir  = Join-Path (Join-Path $projectsDir $dirName) 'PROJECT.md'
+
+$descriptor = ''
+if (Test-Path -LiteralPath $descriptorFile) {
+    $descriptor = $descriptorFile
+} elseif (Test-Path -LiteralPath $descriptorDir) {
+    $descriptor = $descriptorDir
+}
+
+# ─── Build context output ─────────────────────────────────────────────
+$context = ''
+
+if ($ecosystem) {
+    $context = "[arka:project-context] Ecosystem: $ecosystemName ($ecosystem) | Stack: $stack | Use /arka-$ecosystem for dedicated squad routing."
+} elseif ($stack -ne 'unknown') {
+    $context = "[arka:project-context] Stack: $stack | No ecosystem assigned. Use /arka onboard to register this project."
+}
+
+if ($descriptor) {
+    $context = "$context Descriptor: $descriptor"
+}
+
+if ($context) {
+    [pscustomobject]@{ additionalContext = $context } | ConvertTo-Json -Compress
+}

package/config/hooks/post-tool-use.ps1

@@ -0,0 +1,347 @@
+# ============================================================================
+# ArkaOS — PostToolUse Hook (Gotchas Memory) (Windows / PowerShell 5.1+)
+#
+# Port of config/hooks/post-tool-use.sh. Detects errors emitted by tool runs
+# and records recurring patterns in a local gotchas file so ArkaOS can learn
+# which mistakes repeat across projects.
+#
+# Contract:
+# - Reads a hook payload JSON from stdin (tool_name, tool_output, exit_code,
+#   cwd).
+# - Always exits 0 and writes `{}` on stdout — PostToolUse does not inject
+#   context.
+# - Side effect: updates %USERPROFILE%\.arkaos\gotchas.json and
+#   %USERPROFILE%\.arkaos\hook-metrics.json.
+#
+# State files live under the canonical v2 runtime directory `~/.arkaos/`.
+# Older builds of the bash twin used `~/.arka-os/` (with a dash); the
+# bash hook has been fixed in the same commit series, and the installer
+# update path now carries legacy state forward on the first update.
+# ============================================================================
+
+$ErrorActionPreference = 'Stop'
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+
+# Hard timeout budget for the whole hook: 5 seconds (same as settings).
+$sw = [System.Diagnostics.Stopwatch]::StartNew()
+
+# ─── Helper functions (used by both gotchas and metrics blocks) ───────
+# Defined at module scope so the metrics-write block at the bottom of
+# the file can still reach them when `shouldProcessGotchas` is false
+# and the gotchas branch is skipped.
+
+function Acquire-FileLock {
+    param([string]$LockPath, [int]$TimeoutMs = 3000)
+    $deadline = [Environment]::TickCount + $TimeoutMs
+    while ([Environment]::TickCount -lt $deadline) {
+        try {
+            $fs = [System.IO.File]::Open(
+                $LockPath,
+                [System.IO.FileMode]::OpenOrCreate,
+                [System.IO.FileAccess]::ReadWrite,
+                [System.IO.FileShare]::None
+            )
+            return $fs
+        } catch {
+            Start-Sleep -Milliseconds 50
+        }
+    }
+    return $null
+}
+
+# PS 5.1's `Set-Content -Encoding UTF8` writes a BOM; tools that parse
+# UTF-8 strictly (jq, python's json module, etc.) treat the BOM as a
+# stray character. Always write JSON state files BOM-less via the .NET
+# API with an explicit UTF8Encoding($false).
+function Write-JsonAtomic {
+    param([string]$Path, [string]$Json)
+    $tmp = "$Path.tmp"
+    $utf8NoBom = [System.Text.UTF8Encoding]::new($false)
+    [System.IO.File]::WriteAllText($tmp, $Json, $utf8NoBom)
+    Move-Item -Force -LiteralPath $tmp -Destination $Path
+}
+
+# PS 5.1 `ConvertTo-Json` on a single-item collection serializes as a
+# bare object, not a single-element array. We always want `[...]` on
+# disk, even with 0 or 1 entries, so state files stay homogeneous and
+# round-trip cleanly. This helper forces array wrapping by serializing
+# each item and joining manually.
+function ConvertTo-JsonArray {
+    param($Items, [int]$Depth = 10)
+    $arr = @($Items)
+    if ($arr.Count -eq 0) { return '[]' }
+    $parts = foreach ($item in $arr) {
+        $item | ConvertTo-Json -Depth $Depth -Compress
+    }
+    return '[' + ($parts -join ',') + ']'
+}
+
+# ArrayList survives ConvertTo-Json as a proper JSON array even with
+# 0 or 1 elements, unlike `@()` which PS 5.1 happily collapses.
+function New-StringArrayList {
+    param([string[]]$Initial)
+    $list = New-Object System.Collections.ArrayList
+    if ($Initial) {
+        foreach ($s in $Initial) {
+            if ($null -ne $s -and $s -ne '') { [void]$list.Add($s) }
+        }
+    }
+    return ,$list
+}
+
+# ─── Read hook payload from stdin (with empty-stdin tolerance) ────────
+# On Claude Code Windows v2.1.97 the hook stdin pipe is opened but the
+# parent writes zero bytes before closing (upstream bug — see
+# Projects/ARKA OS/Windows Handoff.md canary data). We still want to
+# log the metric that proves the hook fired, so instead of early-exiting
+# on empty stdin we just skip the gotchas-processing block and fall
+# through to the metrics write + final '{}' at the bottom of the file.
+$stdinText = [Console]::In.ReadToEnd()
+$shouldProcessGotchas = $true
+$payload = $null
+$toolName = ''
+$toolOutput = ''
+$exitCode = '0'
+$cwd = ''
+
+if ([string]::IsNullOrWhiteSpace($stdinText)) {
+    $shouldProcessGotchas = $false
+} else {
+    try {
+        $payload = $stdinText | ConvertFrom-Json
+    } catch {
+        $shouldProcessGotchas = $false
+    }
+}
+
+if ($shouldProcessGotchas -and $null -ne $payload) {
+    $toolName   = if ($null -ne $payload.tool_name)   { [string]$payload.tool_name   } else { '' }
+    $toolOutput = if ($null -ne $payload.tool_output) { [string]$payload.tool_output } else { '' }
+    $exitCode   = if ($null -ne $payload.exit_code)   { [string]$payload.exit_code   } else { '0' }
+    $cwd        = if ($null -ne $payload.cwd)         { [string]$payload.cwd         } else { '' }
+
+    # ─── Only process when there is actually an error ─────────────────
+    $errorPattern = '(?i)(error:|fatal:|exception:|failed|ENOENT|EACCES|EPERM|panic:)'
+    if ($exitCode -eq '0' -or [string]::IsNullOrEmpty($exitCode)) {
+        if ($toolOutput -notmatch $errorPattern) {
+            $shouldProcessGotchas = $false
+        }
+    }
+}
+
+# Paths that the metrics block needs are declared up here, outside the
+# gotchas-processing branch, so the metrics write at the very bottom of
+# the file works even when `shouldProcessGotchas` is false (empty stdin,
+# invalid JSON, no error pattern, etc.).
+$arkaosRuntimeDir = Join-Path $env:USERPROFILE '.arkaos'
+$null = New-Item -ItemType Directory -Force -Path $arkaosRuntimeDir -ErrorAction SilentlyContinue
+
+# Gotchas processing lives inside a `do { ... } while ($false)` single-
+# iteration loop so any inner step that used to `exit 0` can now `break`
+# out of the gotchas block without bypassing the metrics write.
+if ($shouldProcessGotchas) { do {
+
+# ─── Extract first meaningful error line ─────────────────────────────
+$lines = $toolOutput -split "`r?`n"
+$errorLineRegex = '(?i)(error|fatal|exception|failed|ENOENT|EACCES|EPERM|panic|cannot|not found|permission denied)'
+$errorLine = $null
+foreach ($ln in $lines) {
+    if ($ln -match $errorLineRegex) { $errorLine = $ln; break }
+}
+if ([string]::IsNullOrWhiteSpace($errorLine)) {
+    # Fallback: first-5-lines-tail-1, same as `head -5 | tail -1` in bash.
+    $firstFive = @($lines | Select-Object -First 5)
+    if ($firstFive.Count -gt 0) { $errorLine = $firstFive[-1] }
+}
+if ([string]::IsNullOrWhiteSpace($errorLine)) {
+    break
+}
+
+# ─── Normalize pattern (matches bash sed chain exactly) ───────────────
+$pattern = $errorLine
+$pattern = $pattern -replace '[0-9]{4}-[0-9]{2}-[0-9]{2}[T ][0-9]{2}:[0-9]{2}:[0-9]{2}[^ ]*', 'TIMESTAMP'
+$pattern = $pattern -replace '[0-9a-f]{7,40}', 'HASH'
+$pattern = $pattern -replace 'line [0-9]+', 'line N'
+$pattern = $pattern -replace ':[0-9]+:', ':N:'
+if ($pattern.Length -gt 200) { $pattern = $pattern.Substring(0, 200) }
+if ([string]::IsNullOrWhiteSpace($pattern)) {
+    break
+}
+
+# ─── Categorize ───────────────────────────────────────────────────────
+$category = 'general'
+if     ($errorLine -match '(?i)(artisan|eloquent|laravel|blade|migration|composer|php )')                  { $category = 'laravel' }
+elseif ($errorLine -match '(?i)(npm|node|vue|react|nuxt|next|vite|webpack|typescript|tsx|jsx)')            { $category = 'frontend' }
+elseif ($errorLine -match '(?i)(git |merge|rebase|checkout|branch|commit|push|pull)')                     { $category = 'git' }
+elseif ($errorLine -match '(?i)(sql|postgres|mysql|database|migration|table|column|constraint)')           { $category = 'database' }
+elseif ($errorLine -match '(?i)(permission|denied|EACCES|EPERM|chmod|chown|sudo)')                         { $category = 'permissions' }
+elseif ($errorLine -match '(?i)(test|assert|expect|jest|phpunit|bats|coverage)')                           { $category = 'testing' }
+
+# ─── Match fix suggestion from gotchas-fixes.json ─────────────────────
+$arkaSkillRoot = if ($env:ARKA_OS) { $env:ARKA_OS } else { Join-Path $env:USERPROFILE '.claude\skills\arka' }
+$fixesFile = Join-Path $arkaSkillRoot 'config\gotchas-fixes.json'
+if (-not (Test-Path -LiteralPath $fixesFile)) {
+    $repoPathFile = Join-Path $arkaSkillRoot '.repo-path'
+    if (Test-Path -LiteralPath $repoPathFile) {
+        try {
+            $repoPath = (Get-Content -Raw -LiteralPath $repoPathFile -Encoding UTF8).Trim()
+            if ($repoPath) {
+                $candidate = Join-Path $repoPath 'config\gotchas-fixes.json'
+                if (Test-Path -LiteralPath $candidate) { $fixesFile = $candidate }
+            }
+        } catch { }
+    }
+}
+
+$suggestion = ''
+if (Test-Path -LiteralPath $fixesFile) {
+    try {
+        $fixes = (Get-Content -Raw -LiteralPath $fixesFile -Encoding UTF8 | ConvertFrom-Json).fixes
+        foreach ($fix in @($fixes)) {
+            if ($fix.pattern_match -and ($errorLine -imatch [string]$fix.pattern_match)) {
+                $suggestion = [string]$fix.suggestion
+                break
+            }
+        }
+    } catch { }
+}
+
+# ─── Detect active project ────────────────────────────────────────────
+$project = ''
+if ($cwd) {
+    try {
+        $repoPathFile = Join-Path $arkaSkillRoot '.repo-path'
+        if (Test-Path -LiteralPath $repoPathFile) {
+            $repoPath = (Get-Content -Raw -LiteralPath $repoPathFile -Encoding UTF8).Trim()
+            $projectsDir = Join-Path $repoPath 'projects'
+            if ($repoPath -and (Test-Path -LiteralPath $projectsDir -PathType Container)) {
+                foreach ($projDir in (Get-ChildItem -LiteralPath $projectsDir -Directory -ErrorAction SilentlyContinue)) {
+                    $projectPathFile = Join-Path $projDir.FullName '.project-path'
+                    if (Test-Path -LiteralPath $projectPathFile) {
+                        $projPath = (Get-Content -Raw -LiteralPath $projectPathFile -Encoding UTF8).Trim()
+                        if ($projPath -and $cwd.StartsWith($projPath)) {
+                            $project = $projDir.Name
+                            break
+                        }
+                    }
+                }
+            }
+        }
+    } catch { }
+    if (-not $project) { $project = Split-Path -Leaf $cwd.TrimEnd('\','/') }
+}
+
+# ─── Update ~/.arkaos/gotchas.json (best-effort under a file lock) ────
+# $arkaosRuntimeDir was declared at the top of the script so the metrics
+# block can always reach it.
+$gotchasFile  = Join-Path $arkaosRuntimeDir 'gotchas.json'
+$gotchasLock  = Join-Path $arkaosRuntimeDir 'gotchas.lock'
+
+$lock = Acquire-FileLock -LockPath $gotchasLock
+if ($null -ne $lock) {
+    try {
+        $now = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
+
+        $gotchas = @()
+        if (Test-Path -LiteralPath $gotchasFile) {
+            try {
+                $raw = Get-Content -Raw -LiteralPath $gotchasFile -Encoding UTF8
+                if ($raw -and $raw.Trim()) {
+                    $parsed = $raw | ConvertFrom-Json
+                    $gotchas = @($parsed)
+                }
+            } catch {
+                $gotchas = @()
+            }
+        }
+
+        $existingIdx = -1
+        for ($i = 0; $i -lt $gotchas.Count; $i++) {
+            if ([string]$gotchas[$i].pattern -eq $pattern) {
+                $existingIdx = $i
+                break
+            }
+        }
+
+        if ($existingIdx -ge 0) {
+            $entry = $gotchas[$existingIdx]
+            $entry.count      = [int]$entry.count + 1
+            $entry.last_seen  = $now
+            if ($project) {
+                $existingProjects = @()
+                if ($entry.projects) { $existingProjects = @($entry.projects) }
+                if ($existingProjects -notcontains $project) {
+                    $existingProjects += $project
+                }
+                $entry.projects = (New-StringArrayList -Initial $existingProjects)
+            }
+            if ($suggestion -and [string]::IsNullOrEmpty([string]$entry.suggestion)) {
+                $entry | Add-Member -NotePropertyName suggestion -NotePropertyValue $suggestion -Force
+            }
+            $gotchas[$existingIdx] = $entry
+        } else {
+            $fullPattern = if ($errorLine.Length -gt 500) { $errorLine.Substring(0, 500) } else { $errorLine }
+            $projectsList = if ($project) {
+                New-StringArrayList -Initial @($project)
+            } else {
+                New-StringArrayList
+            }
+            $newEntry = [pscustomobject][ordered]@{
+                pattern       = $pattern
+                full_pattern  = $fullPattern
+                category      = $category
+                tool          = $toolName
+                count         = 1
+                first_seen    = $now
+                last_seen     = $now
+                projects      = $projectsList
+                suggestion    = if ($suggestion) { $suggestion } else { $null }
+            }
+            $gotchas = @($gotchas) + $newEntry
+        }
+
+        # Keep top 100 by count desc. Force array with @() after the
+        # pipeline — PS 5.1 unwraps to a scalar when only one remains.
+        $gotchas = @($gotchas | Sort-Object -Property count -Descending | Select-Object -First 100)
+
+        Write-JsonAtomic -Path $gotchasFile -Json (ConvertTo-JsonArray -Items $gotchas -Depth 10)
+    } catch {
+        # Swallow — gotchas tracking is best-effort, must not fail the hook.
+    } finally {
+        $lock.Close()
+        $lock.Dispose()
+    }
+}
+
+} while ($false) }  # end: do/while single-iteration + if ($shouldProcessGotchas)
+
+# ─── Log hook metrics (best-effort) ───────────────────────────────────
+$metricsFile = Join-Path $arkaosRuntimeDir 'hook-metrics.json'
+$metricsLock = Join-Path $arkaosRuntimeDir 'hook-metrics.lock'
+$metricsLockHandle = Acquire-FileLock -LockPath $metricsLock -TimeoutMs 2000
+if ($null -ne $metricsLockHandle) {
+    try {
+        $metrics = @()
+        if (Test-Path -LiteralPath $metricsFile) {
+            try {
+                $raw = Get-Content -Raw -LiteralPath $metricsFile -Encoding UTF8
+                if ($raw -and $raw.Trim()) { $metrics = @(($raw | ConvertFrom-Json)) }
+            } catch { $metrics = @() }
+        }
+        $metrics = @($metrics) + ([pscustomobject]@{
+            hook        = 'post-tool-use'
+            duration_ms = [int]$sw.ElapsedMilliseconds
+            timestamp   = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
+        })
+        if ($metrics.Count -gt 500) { $metrics = @($metrics[-500..-1]) }
+        Write-JsonAtomic -Path $metricsFile -Json (ConvertTo-JsonArray -Items $metrics -Depth 5)
+    } catch {
+        # Metrics are non-critical.
+    } finally {
+        $metricsLockHandle.Close()
+        $metricsLockHandle.Dispose()
+    }
+}
+
+# Silent output — PostToolUse does not inject context.
+'{}'

package/config/hooks/post-tool-use.sh

@@ -105,11 +105,11 @@ if [ -n "$CWD" ]; then
 fi
 
 # ─── Store in gotchas.json ────────────────────────────────────────────────
-GOTCHAS_FILE="$HOME/.arka-os/gotchas.json"
-mkdir -p "$HOME/.arka-os"
+GOTCHAS_FILE="$HOME/.arkaos/gotchas.json"
+mkdir -p "$HOME/.arkaos"
 
 # Use flock for concurrent safety (fallback if flock not available on macOS)
-LOCK_FILE="$HOME/.arka-os/gotchas.lock"
+LOCK_FILE="$HOME/.arkaos/gotchas.lock"
 if command -v flock &>/dev/null; then
   LOCK_CMD="flock -w 3 200"
 else
@@ -172,9 +172,9 @@ fi
 
 # ─── Log Metrics ─────────────────────────────────────────────────────────
 _DURATION_MS=$(_hook_ms)
-METRICS_FILE="$HOME/.arka-os/hook-metrics.json"
-METRICS_LOCK="$HOME/.arka-os/hook-metrics.lock"
-mkdir -p "$HOME/.arka-os"
+METRICS_FILE="$HOME/.arkaos/hook-metrics.json"
+METRICS_LOCK="$HOME/.arkaos/hook-metrics.lock"
+mkdir -p "$HOME/.arkaos"
 (
   if command -v flock &>/dev/null; then flock -w 2 200; else true; fi
   [ ! -f "$METRICS_FILE" ] && echo '[]' > "$METRICS_FILE"