@ekkos/cli 0.2.9 → 0.2.11

package/dist/utils/state.d.ts

@@ -17,6 +17,8 @@ export interface EkkosState {
     turnNumber: number;
     lastUpdated: string;
     projectPath: string;
+    userId?: string;
+    userEmail?: string;
 }
 export interface EkkosConfig {
     hookApiKey?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekkos/cli",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "description": "Setup ekkOS memory for AI coding assistants (Claude Code, Cursor, Windsurf)",
   "main": "dist/index.js",
   "bin": {

package/templates/ekkos-manifest.json

@@ -0,0 +1,223 @@
+{
+  "$schema": "https://ekkos.dev/schemas/manifest-v1.json",
+  "manifestVersion": "1.0.0",
+  "generatedAt": "2026-01-21T03:41:22.207Z",
+  "platforms": {
+    "darwin": {
+      "configDir": "~/.ekkos",
+      "globalHooksDir": "~/.claude/hooks",
+      "shell": "bash"
+    },
+    "linux": {
+      "configDir": "~/.ekkos",
+      "globalHooksDir": "~/.claude/hooks",
+      "shell": "bash"
+    },
+    "win32": {
+      "configDir": "%USERPROFILE%\\.ekkos",
+      "globalHooksDir": "%USERPROFILE%\\.claude\\hooks",
+      "shell": "powershell"
+    }
+  },
+  "files": {
+    "managed": [
+      {
+        "source": "shared/session-words.json",
+        "destination": ".defaults/session-words.json",
+        "description": "Default session word lists (managed fallback)",
+        "checksum": "c64af03b9ae58d8c94e71886f80e590ad3a72fb2dcdbe02812789fecb4773e1a",
+        "overwrite": "always"
+      },
+      {
+        "source": "shared/hooks-enabled.json",
+        "destination": ".defaults/hooks-enabled.json",
+        "description": "Default hooks enablement config (managed fallback)",
+        "checksum": "74b833a1979f1b9467be6dcdeecc024073a4f3c02625b0751f4b1f9d53f143a3",
+        "overwrite": "always"
+      }
+    ],
+    "helpers": [
+      {
+        "source": "helpers/json-parse.cjs",
+        "destination": ".helpers/json-parse.cjs",
+        "description": "Node-based JSON parser (replaces jq dependency)",
+        "checksum": "e421977262b3bffcbec9f6f7a172df6f998f3b4deac64d478ef5a0a17034b026",
+        "executable": true,
+        "overwrite": "always"
+      }
+    ],
+    "userEditable": [
+      {
+        "source": "shared/session-words.json",
+        "destination": "session-words.json",
+        "description": "User-customizable session word lists",
+        "checksum": "c64af03b9ae58d8c94e71886f80e590ad3a72fb2dcdbe02812789fecb4773e1a",
+        "overwrite": "createOnly"
+      },
+      {
+        "source": "shared/hooks-enabled.json",
+        "destination": "hooks-enabled.json",
+        "description": "User-controlled hook enablement",
+        "checksum": "74b833a1979f1b9467be6dcdeecc024073a4f3c02625b0751f4b1f9d53f143a3",
+        "overwrite": "createOnly"
+      }
+    ],
+    "hooks": {
+      "bash": [
+        {
+          "source": "hooks/user-prompt-submit.sh",
+          "destination": "user-prompt-submit.sh",
+          "description": "User prompt submit hook (Unix)",
+          "checksum": "0e006eb7becba874f34fc622c9ee83b3c96a6e00daf95db840369894af94abf3",
+          "executable": true
+        },
+        {
+          "source": "hooks/stop.sh",
+          "destination": "stop.sh",
+          "description": "Session stop hook (Unix)",
+          "checksum": "fd436ea847bf6fbe367f8aa61ddf6d97e8605837badc3af8d433b59599ef6615",
+          "executable": true
+        },
+        {
+          "source": "hooks/session-start.sh",
+          "destination": "session-start.sh",
+          "description": "Session start hook (Unix)",
+          "checksum": "8d17fd3203045589f0c410f465b0d1e98d6ed24dc3bc99f44878e44e9501a22d",
+          "executable": true
+        },
+        {
+          "source": "hooks/assistant-response.sh",
+          "destination": "assistant-response.sh",
+          "description": "Assistant response hook (Unix)",
+          "checksum": "11c3b84aff29552f8a28b59851a4fdc7de4414d28161cca7418dfc93e0c64eac",
+          "executable": true
+        }
+      ],
+      "powershell": [
+        {
+          "source": "hooks/user-prompt-submit.ps1",
+          "destination": "user-prompt-submit.ps1",
+          "description": "User prompt submit hook (Windows)",
+          "checksum": "ba044ec066935a9413811e53fd70f42f0ffd959fc361b746c6b54768ac8c6fb9"
+        },
+        {
+          "source": "hooks/stop.ps1",
+          "destination": "stop.ps1",
+          "description": "Session stop hook (Windows)",
+          "checksum": "455d9dfca8cea2f8289604ca2389b8e43c8af380fbcc5e2eef18382d30e4be6d"
+        },
+        {
+          "source": "hooks/session-start.ps1",
+          "destination": "session-start.ps1",
+          "description": "Session start hook (Windows)",
+          "checksum": "0897603df2b3261857be79108c0831b0fbc3744722b4923ce632844e7c6483c6"
+        },
+        {
+          "source": "hooks/assistant-response.ps1",
+          "destination": "assistant-response.ps1",
+          "description": "Assistant response hook (Windows)",
+          "checksum": "83fb65cec1cb9b1b9ef7a2036c9440e8b6ced16d82a2623b5353899918ae9653"
+        }
+      ],
+      "lib": [
+        {
+          "source": "hooks/lib/contract.sh",
+          "destination": "lib/contract.sh",
+          "description": "Hook contract library",
+          "checksum": "1d86128a2a4a25e653a02c4eb08dbfd28db53063c618cd43b85f0603a135e8b2",
+          "executable": true
+        },
+        {
+          "source": "hooks/lib/state.sh",
+          "destination": "lib/state.sh",
+          "description": "Hook state management library",
+          "checksum": "ba72c00a1fb0f6768e37aff754ad6ac0e8e20aa0b9b393193e2d92357cac5a71",
+          "executable": true
+        }
+      ]
+    }
+  },
+  "projectStubs": {
+    "description": "Delegating stub hooks for project-level installation. These source global hooks first, then load project-specific overrides.",
+    "bash": [
+      {
+        "source": "project-stubs/user-prompt-submit.sh",
+        "destination": "user-prompt-submit.sh",
+        "description": "Project delegating stub for user-prompt-submit (Unix)",
+        "checksum": "47cc6b45dbb027e321c136f7c0935bae0d3dc349f01912fbe42ae27d382e297d",
+        "executable": true
+      },
+      {
+        "source": "project-stubs/stop.sh",
+        "destination": "stop.sh",
+        "description": "Project delegating stub for stop (Unix)",
+        "checksum": "a429c5ee596e6c975df32feb8ba952c77c0492d91bd9cd80f9eac2e721040eb4",
+        "executable": true
+      },
+      {
+        "source": "project-stubs/session-start.sh",
+        "destination": "session-start.sh",
+        "description": "Project delegating stub for session-start (Unix)",
+        "checksum": "189379e81e000153d057e49afd71791d28a6b73baab4b49b39de34918a00c493",
+        "executable": true
+      }
+    ],
+    "powershell": [
+      {
+        "source": "project-stubs/user-prompt-submit.ps1",
+        "destination": "user-prompt-submit.ps1",
+        "description": "Project delegating stub for user-prompt-submit (Windows)",
+        "checksum": "86cfea6a6e1181fc6b9180e82a3e34e1ba8e8b412c65bdf013d2367ea8b93283"
+      },
+      {
+        "source": "project-stubs/stop.ps1",
+        "destination": "stop.ps1",
+        "description": "Project delegating stub for stop (Windows)",
+        "checksum": "042f815ed455c5b5e51291b8740deafaea827c594695b270f4d4e4e5086bc234"
+      },
+      {
+        "source": "project-stubs/session-start.ps1",
+        "destination": "session-start.ps1",
+        "description": "Project delegating stub for session-start (Windows)",
+        "checksum": "14081806c7ca63a67999314f31e14a6c1293e57a8ce64335122f359e3bb8fba4"
+      }
+    ]
+  },
+  "cli": {
+    "minVersion": "0.2.9",
+    "legacySupported": true,
+    "requiredCommands": {
+      "0.2.9": [
+        "run",
+        "config"
+      ],
+      "0.3.0": [
+        "run",
+        "config",
+        "hooks"
+      ]
+    }
+  },
+  "validation": {
+    "requiredFiles": [
+      "shared/session-words.json",
+      "shared/hooks-enabled.json",
+      "helpers/json-parse.cjs",
+      "hooks/user-prompt-submit.sh",
+      "hooks/user-prompt-submit.ps1",
+      "hooks/stop.sh",
+      "hooks/stop.ps1",
+      "hooks/session-start.sh",
+      "hooks/session-start.ps1",
+      "hooks/assistant-response.sh",
+      "hooks/assistant-response.ps1",
+      "project-stubs/user-prompt-submit.sh",
+      "project-stubs/user-prompt-submit.ps1",
+      "project-stubs/stop.sh",
+      "project-stubs/stop.ps1",
+      "project-stubs/session-start.sh",
+      "project-stubs/session-start.ps1"
+    ],
+    "checksumAlgorithm": "sha256"
+  }
+}

package/templates/helpers/json-parse.cjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * json-parse.cjs - Minimal JSON parser for ekkOS hooks
+ * Eliminates jq dependency for cross-platform compatibility
+ *
+ * Usage: json-parse.cjs <file> [path]
+ *
+ * Examples:
+ *   json-parse.cjs config.json                     # Output entire file
+ *   json-parse.cjs config.json .apiKey             # Output single value
+ *   json-parse.cjs words.json .adjectives          # Output array (one per line)
+ *   json-parse.cjs hooks.json .targets.claude.stop # Nested path
+ *
+ * Exit codes:
+ *   0 - Success (including empty/null result)
+ *   1 - Error (file not found, invalid JSON, etc.)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const args = process.argv.slice(2);
+
+if (args.length < 1) {
+  console.error('Usage: json-parse.cjs <file> [path]');
+  console.error('Example: json-parse.cjs config.json .apiKey');
+  process.exit(1);
+}
+
+const filePath = args[0];
+const jsonPath = args[1] || null;
+
+// Check file exists
+if (!fs.existsSync(filePath)) {
+  console.error(`Error: File not found: ${filePath}`);
+  process.exit(1);
+}
+
+let data;
+try {
+  const content = fs.readFileSync(filePath, 'utf8');
+  data = JSON.parse(content);
+} catch (err) {
+  console.error(`Error: Failed to parse JSON: ${err.message}`);
+  process.exit(1);
+}
+
+// If no path specified, output entire JSON
+if (!jsonPath) {
+  console.log(JSON.stringify(data, null, 2));
+  process.exit(0);
+}
+
+// Parse path and extract value
+// Supports: .foo.bar, .foo[0], .foo.bar[1].baz
+function extractValue(obj, pathStr) {
+  if (!pathStr || pathStr === '.') return obj;
+
+  // Remove leading dot if present
+  const cleanPath = pathStr.startsWith('.') ? pathStr.slice(1) : pathStr;
+  if (!cleanPath) return obj;
+
+  // Split on . and [ but keep the brackets for array access
+  const parts = cleanPath.split(/\.|\[|\]/).filter(Boolean);
+
+  let result = obj;
+  for (const part of parts) {
+    if (result === undefined || result === null) {
+      return undefined;
+    }
+    result = result[part];
+  }
+  return result;
+}
+
+const result = extractValue(data, jsonPath);
+
+// Handle different result types
+if (result === undefined || result === null) {
+  // Empty output, exit 0 (not an error - just no value)
+  process.exit(0);
+}
+
+if (Array.isArray(result)) {
+  // Output array items one per line (like jq -r '.[]')
+  for (const item of result) {
+    if (typeof item === 'object') {
+      console.log(JSON.stringify(item));
+    } else {
+      console.log(item);
+    }
+  }
+} else if (typeof result === 'object') {
+  console.log(JSON.stringify(result, null, 2));
+} else if (typeof result === 'boolean') {
+  console.log(result ? 'true' : 'false');
+} else {
+  console.log(result);
+}
+
+process.exit(0);

package/templates/hooks/assistant-response.ps1

@@ -0,0 +1,256 @@
+# ═══════════════════════════════════════════════════════════════════════════
+# ekkOS_ Hook: AssistantResponse - Process Claude's response (Windows)
+# MANAGED BY ekkos-connect - DO NOT EDIT DIRECTLY
+# EKKOS_MANAGED=1
+# EKKOS_MANIFEST_SHA256=<computed-at-build>
+# EKKOS_TEMPLATE_VERSION=1.0.0
+#
+# Per ekkOS Onboarding Spec v1.2 FINAL + ADDENDUM:
+# - All persisted records MUST include: instanceId, sessionId, sessionName
+# - Uses EKKOS_INSTANCE_ID env var for multi-session isolation
+# ═══════════════════════════════════════════════════════════════════════════
+
+$ErrorActionPreference = "SilentlyContinue"
+
+# ═══════════════════════════════════════════════════════════════════════════
+# CONFIG PATHS - No hardcoded word arrays per spec v1.2 Addendum
+# ═══════════════════════════════════════════════════════════════════════════
+$EkkosConfigDir = if ($env:EKKOS_CONFIG_DIR) { $env:EKKOS_CONFIG_DIR } else { "$env:USERPROFILE\.ekkos" }
+$HooksEnabledJson = "$EkkosConfigDir\hooks-enabled.json"
+$HooksEnabledDefault = "$EkkosConfigDir\.defaults\hooks-enabled.json"
+$SessionWordsJson = "$EkkosConfigDir\session-words.json"
+$SessionWordsDefault = "$EkkosConfigDir\.defaults\session-words.json"
+
+# ═══════════════════════════════════════════════════════════════════════════
+# INSTANCE ID - Multi-session isolation per v1.2 ADDENDUM
+# ═══════════════════════════════════════════════════════════════════════════
+$EkkosInstanceId = if ($env:EKKOS_INSTANCE_ID) { $env:EKKOS_INSTANCE_ID } else { "default" }
+
+# ═══════════════════════════════════════════════════════════════════════════
+# CHECK ENABLEMENT - Respect hooks-enabled.json
+# ═══════════════════════════════════════════════════════════════════════════
+function Test-HookEnabled {
+    param([string]$HookName)
+
+    $enabledFile = $HooksEnabledJson
+    if (-not (Test-Path $enabledFile)) {
+        $enabledFile = $HooksEnabledDefault
+    }
+
+    if (-not (Test-Path $enabledFile)) {
+        # No enablement file = all enabled by default
+        return $true
+    }
+
+    try {
+        $config = Get-Content $enabledFile -Raw | ConvertFrom-Json
+
+        # Check claude.enabled array
+        if ($config.claude -and $config.claude.enabled) {
+            $enabledHooks = $config.claude.enabled
+            if ($enabledHooks -contains $HookName -or $enabledHooks -contains "assistant-response") {
+                return $true
+            }
+            return $false
+        }
+
+        return $true  # Default to enabled if no config
+    } catch {
+        return $true  # Default to enabled on error
+    }
+}
+
+# Check if this hook is enabled
+if (-not (Test-HookEnabled "assistant-response")) {
+    exit 0
+}
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Load session words from JSON file - NO HARDCODED ARRAYS
+# ═══════════════════════════════════════════════════════════════════════════
+$script:SessionWords = $null
+
+function Load-SessionWords {
+    $wordsFile = $SessionWordsJson
+
+    # Fallback to managed defaults if user file missing/invalid
+    if (-not (Test-Path $wordsFile)) {
+        $wordsFile = $SessionWordsDefault
+    }
+
+    if (-not (Test-Path $wordsFile)) {
+        return $null
+    }
+
+    try {
+        $script:SessionWords = Get-Content $wordsFile -Raw | ConvertFrom-Json
+    } catch {
+        return $null
+    }
+}
+
+# ═══════════════════════════════════════════════════════════════════════════
+# SESSION NAME (UUID to words) - Uses external session-words.json
+# ═══════════════════════════════════════════════════════════════════════════
+function Convert-UuidToWords {
+    param([string]$uuid)
+
+    # Load session words if not already loaded
+    if (-not $script:SessionWords) {
+        Load-SessionWords
+    }
+
+    # Handle missing session words gracefully
+    if (-not $script:SessionWords) {
+        return "unknown-session"
+    }
+
+    $adjectives = $script:SessionWords.adjectives
+    $nouns = $script:SessionWords.nouns
+    $verbs = $script:SessionWords.verbs
+
+    if (-not $adjectives -or -not $nouns -or -not $verbs) {
+        return "unknown-session"
+    }
+
+    if (-not $uuid -or $uuid -eq "unknown") { return "unknown-session" }
+
+    $clean = $uuid -replace "-", ""
+    if ($clean.Length -lt 6) { return "unknown-session" }
+
+    try {
+        $a = [Convert]::ToInt32($clean.Substring(0,2), 16) % $adjectives.Length
+        $n = [Convert]::ToInt32($clean.Substring(2,2), 16) % $nouns.Length
+        $an = [Convert]::ToInt32($clean.Substring(4,2), 16) % $verbs.Length
+
+        return "$($adjectives[$a])-$($nouns[$n])-$($verbs[$an])"
+    } catch {
+        return "unknown-session"
+    }
+}
+
+# ═══════════════════════════════════════════════════════════════════════════
+# READ INPUT
+# ═══════════════════════════════════════════════════════════════════════════
+$inputJson = [Console]::In.ReadToEnd()
+if (-not $inputJson) { exit 0 }
+
+try {
+    $input = $inputJson | ConvertFrom-Json
+} catch {
+    exit 0
+}
+
+# Extract response content
+$assistantResponse = $input.response
+if (-not $assistantResponse) { $assistantResponse = $input.message }
+if (-not $assistantResponse) { $assistantResponse = $input.content }
+if (-not $assistantResponse) { exit 0 }
+
+# Get session ID
+$rawSessionId = $input.session_id
+if (-not $rawSessionId -or $rawSessionId -eq "null") { $rawSessionId = "unknown" }
+
+# Fallback: read session_id from saved state
+if ($rawSessionId -eq "unknown") {
+    $stateFile = Join-Path $env:USERPROFILE ".claude\state\current-session.json"
+    if (Test-Path $stateFile) {
+        try {
+            $state = Get-Content $stateFile -Raw | ConvertFrom-Json
+            $rawSessionId = $state.session_id
+        } catch {}
+    }
+}
+
+$sessionName = Convert-UuidToWords $rawSessionId
+
+# ═══════════════════════════════════════════════════════════════════════════
+# READ TURN STATE
+# ═══════════════════════════════════════════════════════════════════════════
+$stateFile = Join-Path $env:USERPROFILE ".claude\state\hook-state.json"
+$turn = 0
+
+if (Test-Path $stateFile) {
+    try {
+        $hookState = Get-Content $stateFile -Raw | ConvertFrom-Json
+        $turn = [int]$hookState.turn
+    } catch {
+        $turn = 0
+    }
+}
+
+# ═══════════════════════════════════════════════════════════════════════════
+# PATTERN TRACKING (detect [ekkOS_SELECT] blocks)
+# ═══════════════════════════════════════════════════════════════════════════
+$patternIds = @()
+if ($assistantResponse -match '\[ekkOS_SELECT\]') {
+    # Extract pattern IDs from SELECT blocks
+    $selectMatches = [regex]::Matches($assistantResponse, 'id:\s*([a-zA-Z0-9\-_]+)')
+    foreach ($match in $selectMatches) {
+        $patternIds += $match.Groups[1].Value
+    }
+}
+
+# ═══════════════════════════════════════════════════════════════════════════
+# LOCAL CACHE: Tier 0 capture (async, non-blocking)
+# Per v1.2 ADDENDUM: Pass instanceId for namespacing
+# ═══════════════════════════════════════════════════════════════════════════
+$captureCmd = Get-Command "ekkos-capture" -ErrorAction SilentlyContinue
+if ($captureCmd -and $rawSessionId -ne "unknown") {
+    try {
+        # NEW format: ekkos-capture response <instance_id> <session_id> <turn_id> <response> [tools] [files]
+        $responseBase64 = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($assistantResponse))
+        $toolsJson = "[]"
+        $filesJson = "[]"
+
+        # Extract tools used from response
+        $toolMatches = [regex]::Matches($assistantResponse, '\[TOOL:\s*([^\]]+)\]')
+        if ($toolMatches.Count -gt 0) {
+            $tools = $toolMatches | ForEach-Object { $_.Groups[1].Value } | Select-Object -Unique
+            $toolsJson = $tools | ConvertTo-Json -Compress
+        }
+
+        Start-Job -ScriptBlock {
+            param($instanceId, $sessionId, $turnNum, $responseB64, $tools, $files)
+            try {
+                $decoded = [System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($responseB64))
+                & ekkos-capture response $instanceId $sessionId $turnNum $decoded $tools $files 2>&1 | Out-Null
+            } catch {}
+        } -ArgumentList $EkkosInstanceId, $rawSessionId, $turn, $responseBase64, $toolsJson, $filesJson | Out-Null
+    } catch {}
+}
+
+# ═══════════════════════════════════════════════════════════════════════════
+# WORKING MEMORY: Fast capture to API (async, non-blocking)
+# ═══════════════════════════════════════════════════════════════════════════
+$configFile = Join-Path $EkkosConfigDir "config.json"
+if (Test-Path $configFile) {
+    try {
+        $config = Get-Content $configFile -Raw | ConvertFrom-Json
+        $captureToken = $config.hookApiKey
+        if (-not $captureToken) { $captureToken = $config.apiKey }
+
+        if ($captureToken) {
+            Start-Job -ScriptBlock {
+                param($token, $instanceId, $sessionId, $sessionName, $turnNum, $response, $patterns)
+                $body = @{
+                    session_id = $sessionId
+                    session_name = $sessionName
+                    instance_id = $instanceId
+                    turn = $turnNum
+                    response = $response.Substring(0, [Math]::Min(5000, $response.Length))
+                    pattern_ids = $patterns
+                } | ConvertTo-Json
+
+                Invoke-RestMethod -Uri "https://api.ekkos.dev/api/v1/working/turn" `
+                    -Method POST `
+                    -Headers @{ Authorization = "Bearer $token" } `
+                    -ContentType "application/json" `
+                    -Body $body -ErrorAction SilentlyContinue
+            } -ArgumentList $captureToken, $EkkosInstanceId, $rawSessionId, $sessionName, $turn, $assistantResponse, $patternIds | Out-Null
+        }
+    } catch {}
+}
+
+# Silent exit - assistant-response hook should not produce output
+exit 0