@exreve/exk 1.0.0

package/install-service.sh

@@ -0,0 +1,122 @@
+#!/bin/bash
+
+# Install exk CLI as pm2 daemon (runs exk daemon)
+# Works for npm global install (`npm i -g exk`) and standalone
+
+set -e
+
+PM2_APP_NAME="exk_cli"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# EXK_PKG_DIR: set by `exk register` - points to npm package root (node_modules/exk)
+EXK_PKG_DIR="${EXK_PKG_DIR:-$SCRIPT_DIR}"
+# EXK_BIN: path to the exk binary (global npm bin)
+EXK_BIN="${EXK_BIN:-$(command -v exk 2>/dev/null || echo "")}"
+
+INSTALL_DIR="$HOME/.talk-to-code"
+
+# Ensure PATH includes nvm/node for pm2
+if [ -f "$HOME/.nvm/nvm.sh" ]; then
+  . "$HOME/.nvm/nvm.sh"
+fi
+
+# Check for uninstall flag
+if [ "$1" == "--uninstall" ] || [ "$1" == "--remove" ] || [ "$1" == "-u" ] || [ "$1" == "-r" ]; then
+  echo "Uninstalling exk daemon from pm2..."
+
+  if command -v pm2 >/dev/null 2>&1; then
+    pm2 delete "$PM2_APP_NAME" 2>/dev/null || true
+    pm2 save --force 2>/dev/null || true
+  fi
+  rm -f "$INSTALL_DIR/ecosystem.config.cjs" 2>/dev/null || true
+
+  echo ""
+  echo "exk daemon uninstalled from pm2."
+  echo "To remove the package: npm uninstall -g exk"
+  exit 0
+fi
+
+echo "Installing exk daemon as pm2 process (name: $PM2_APP_NAME)..."
+
+# Find exk binary
+if [ -z "$EXK_BIN" ] || [ ! -x "$EXK_BIN" ]; then
+  EXK_BIN="$(command -v exk 2>/dev/null || true)"
+fi
+if [ -z "$EXK_BIN" ]; then
+  echo "Error: exk binary not found in PATH"
+  echo "Make sure exk is installed: npm i -g exk"
+  exit 1
+fi
+
+echo "  exk binary: $EXK_BIN"
+echo "  package dir: $EXK_PKG_DIR"
+
+# Ensure pm2 is available
+if ! command -v pm2 >/dev/null 2>&1; then
+  for nvm_dir in "$HOME/.nvm/versions/node"/*/bin; do
+    [ -d "$nvm_dir" ] && export PATH="$nvm_dir:$PATH"
+  done
+  if ! command -v pm2 >/dev/null 2>&1; then
+    echo "Installing pm2..."
+    (npm install -g pm2 2>/dev/null) || true
+  fi
+  if ! command -v pm2 >/dev/null 2>&1; then
+    echo "Error: pm2 not found. Run: npm install -g pm2"
+    exit 1
+  fi
+fi
+
+# Stop and delete if already running
+pm2 delete "$PM2_APP_NAME" 2>/dev/null || true
+
+# Build PATH for daemon
+NVM_BIN=""
+if [ -d "$HOME/.nvm/versions/node" ]; then
+  for d in "$HOME/.nvm/versions/node"/*/bin; do
+    [ -d "$d" ] && NVM_BIN="${d}:"
+  done
+fi
+NODE_BIN_FALLBACK="$(command -v node 2>/dev/null | xargs dirname 2>/dev/null)"
+[ -n "$NODE_BIN_FALLBACK" ] && NVM_BIN="${NODE_BIN_FALLBACK}:${NVM_BIN}"
+DAEMON_PATH="$HOME/.local/bin:${NVM_BIN}/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+DAEMON_PATH="${DAEMON_PATH//::/:}"
+
+# Create config dir
+mkdir -p "$INSTALL_DIR"
+
+# Use ecosystem file for reliable pm2 config
+ECOSYSTEM="$INSTALL_DIR/ecosystem.config.cjs"
+cat > "$ECOSYSTEM" << ECOSYSTEM_EOF
+module.exports = {
+  apps: [{
+    name: "$PM2_APP_NAME",
+    script: "$EXK_BIN",
+    args: "daemon",
+    env: {
+      HOME: "$HOME",
+      USER: "${USER:-$(whoami)}",
+      PATH: "$DAEMON_PATH",
+      EXK_PKG_DIR: "$EXK_PKG_DIR"
+    }
+  }]
+};
+ECOSYSTEM_EOF
+
+if ! pm2 start "$ECOSYSTEM"; then
+  echo "Error: pm2 start failed. Try running manually: pm2 start $ECOSYSTEM"
+  exit 1
+fi
+
+# Persist across reboots
+pm2 save
+pm2 startup 2>/dev/null || echo "Note: Run 'pm2 startup' as root to enable auto-start on reboot"
+
+echo ""
+echo "exk installed and running as pm2 daemon."
+echo ""
+echo "Commands:"
+echo "  pm2 status                - list processes"
+echo "  pm2 logs $PM2_APP_NAME    - view logs"
+echo "  pm2 restart $PM2_APP_NAME - restart"
+echo ""
+echo "To uninstall: exk uninstall"

package/moduleMcpServer.ts

@@ -0,0 +1,131 @@
+/**
+ * Module MCP Server
+ *
+ * Exposes enabled modules as MCP tools to the agent.
+ * This allows the agent to interact with modules like user-choice through standard tool calls.
+ */
+
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk'
+import type { SdkMcpToolDefinition } from '@anthropic-ai/claude-agent-sdk'
+import { z } from 'zod'
+
+/** MCP tool result shape (matches CallToolResult) */
+type ToolResult = { content: Array<{ type: 'text'; text: string }>; isError?: boolean }
+
+export interface ModuleMcpServerConfig {
+  enabledModules: string[]
+  moduleSettings: Record<string, any>
+  onChoiceRequest?: (request: ChoiceRequest) => Promise<ChoiceResponse>
+}
+
+export interface ChoiceRequest {
+  choiceId: string
+  question: string
+  options: Array<{ label: string; value: string }>
+  timeout?: number
+}
+
+export interface ChoiceResponse {
+  choiceId: string
+  selectedValue: string | null
+}
+
+/**
+ * Create a tool for the user-choice module
+ */
+function createUserChoiceTool(onChoiceRequest?: (request: ChoiceRequest) => Promise<ChoiceResponse>): SdkMcpToolDefinition<any> {
+  const schema = {
+    question: z.string(),
+    options: z.array(z.object({ label: z.string(), value: z.string() })),
+    timeout: z.number().optional()
+  }
+  return tool(
+    'user_choice_request',
+    'Request user input when making decisions. Use this when you need the user to choose between options or provide input on a decision. This tool will present a modal to the user with your question and wait for their response.',
+    schema,
+    async (args, _extra): Promise<ToolResult> => {
+      if (!onChoiceRequest) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: 'Error: User choice is not enabled. Please use an alternative approach or ask the user directly.'
+            }
+          ],
+          isError: true
+        }
+      }
+
+      const choiceId = `choice-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`
+
+      try {
+        const response = await onChoiceRequest({
+          choiceId,
+          question: args.question as string,
+          options: args.options as Array<{ label: string; value: string }>,
+          timeout: args.timeout as number | undefined
+        })
+
+        if (response.selectedValue === null) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: 'The user did not respond within the timeout period. Please proceed with a reasonable default or ask again.'
+              }
+            ]
+          }
+        }
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `The user selected: ${response.selectedValue}`
+            }
+          ]
+        }
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error requesting user choice: ${error instanceof Error ? error.message : String(error)}`
+            }
+          ],
+          isError: true
+        }
+      }
+    }
+  )
+}
+
+/**
+ * Get available tools based on enabled modules
+ */
+function getModuleTools(config: ModuleMcpServerConfig): SdkMcpToolDefinition<any>[] {
+  const tools: SdkMcpToolDefinition<any>[] = []
+
+  // User choice module
+  if (config.enabledModules.includes('user-choice')) {
+    tools.push(createUserChoiceTool(config.onChoiceRequest))
+  }
+
+  // Add more module tools here as they are implemented
+  return tools
+}
+
+/**
+ * Create the module MCP server
+ */
+export function createModuleMcpServer(config: ModuleMcpServerConfig) {
+  const tools = getModuleTools(config)
+
+  const server = createSdkMcpServer({
+    name: 'claude-voice-modules',
+    version: '1.0.0',
+    tools
+  })
+
+  return server
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@exreve/exk",
+  "version": "1.0.0",
+  "description": "exk - Control Claude CLI with voice and programmable interfaces",
+  "type": "module",
+  "bin": {
+    "exk": "./bin/exk"
+  },
+  "files": [
+    "bin",
+    "shared",
+    "skills",
+    "*.ts",
+    "install-service.sh",
+    "container-entrypoint.sh",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "build": "node build-cli-tarball.js",
+    "build:tsc": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "node -e \"require('fs').chmodSync('bin/exk', 0o755)\""
+  },
+  "keywords": [
+    "claude",
+    "cli",
+    "voice",
+    "agent",
+    "talktocode"
+  ],
+  "author": "exreve",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.1.23",
+    "@anthropic-ai/sdk": "^0.74.0",
+    "@fastify/static": "^9.0.0",
+    "@types/node": "^22.10.2",
+    "@xenova/transformers": "^2.17.2",
+    "better-sqlite3": "^9.0.0",
+    "chokidar": "^3.6.0",
+    "commander": "^13.1.0",
+    "express": "^4.18.2",
+    "fastify": "^5.7.2",
+    "node-fetch": "^3.3.2",
+    "pino-pretty": "^11.0.0",
+    "socket.io-client": "^4.8.1",
+    "tsx": "^4.19.0",
+    "uuid": "^11.0.3"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/chokidar": "^2.1.3",
+    "@types/uuid": "^10.0.0",
+    "@vercel/ncc": "^0.38.1",
+    "esbuild": "^0.27.2",
+    "js-confuser": "^1.1.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/projectAnalyzer.ts

@@ -0,0 +1,341 @@
+import { v4 as uuidv4 } from 'uuid'
+import fs from 'fs/promises'
+import path from 'path'
+import type { ProjectConfig } from './shared/types'
+import { agentSessionManager } from './agentSession'
+import type { SessionOutput } from './shared/types'
+
+const CONFIG_FILENAME = '.claude-voice.json'
+
+/**
+ * Analyze project using Claude AI and generate structured JSON configuration
+ */
+export async function analyzeProjectWithClaude(projectPath: string, projectName: string): Promise<ProjectConfig> {
+  // Create a temporary session ID for analysis
+  const analysisSessionId = `analysis-${uuidv4()}`
+  
+  // Build the analysis prompt with structured output requirements
+  const analysisPrompt = `Analyze the project structure at ${projectPath} and generate a comprehensive project configuration.
+
+CRITICAL: You must identify ALL applications/services in this project. Each app will get its own TypeScript runner file and entry in the JSON config.
+
+Please examine:
+1. Project files and directory structure (use Read/Glob tools to explore)
+2. Framework and technology stack (React, Express, FastAPI, Django, etc.)
+3. Apps (applications/services) - each app can be at root or in subdirectories
+4. For each app, identify:
+   - App NAME: unique identifier for the app
+   - App TYPE: "static-frontend" (React/Vue/Angular/Svelte/Next.js static builds) or "backend" (Express/Fastify/FastAPI/Django/etc.)
+   - How to BUILD it (buildCommand - REQUIRED for static frontends)
+   - How to START it (startCommand - REQUIRED for all apps)
+   - How to STOP it (stopCommand - optional, defaults to killing process)
+   - How to RESTART it (restartCommand - optional, defaults to stop + start)
+   - Port number (port - REQUIRED for HTTP apps)
+   - Protocol (http/https/ws/etc.)
+   - HTTP endpoints/routes (endpoints array)
+   - Framework name (react/express/fastify/etc.)
+   - Directory location (relative to project root, empty string "" for root app)
+   - Build output directory (buildDir - for static frontends: dist/build/public)
+   - Environment variables (env object)
+   - Health check URL or command
+5. Check package.json scripts, Makefile, docker-compose.yml, Procfile, vite.config.js, next.config.js, etc. for commands
+6. Detect HTTP endpoints by examining route files, controllers, or API definitions
+7. For static frontends, identify the build output directory (usually dist, build, or public)
+8. Look for multiple apps in monorepos or multi-app projects
+
+IMPORTANT OUTPUT REQUIREMENTS:
+- You must output a JSON file named ".talk-to-code.json" in the project root
+- The JSON must contain ALL apps/services found in the project
+- Each app will be wrapped with a TypeScript runner file (generated automatically)
+- Apps must be configured to work with the runner system
+
+Output ONLY valid JSON matching this exact structure (no markdown, no code blocks, no explanations, just pure JSON):
+
+{
+  "version": "1.0.0",
+  "projectName": "${projectName}",
+  "description": "Description of the project",
+  "apps": [
+    {
+      "name": "app-name",
+      "description": "Optional description",
+      "type": "http",
+      "port": 3000,
+      "protocol": "http",
+      "directory": "relative/path/to/app",
+      "framework": "react",
+      "appType": "static-frontend",
+      "buildDir": "dist",
+      "endpoints": ["/", "/api", "/api/v1"],
+      "env": {},
+      "healthCheck": {
+        "url": "http://localhost:3000/health"
+      },
+      "buildCommand": "npm run build",
+      "startCommand": "npm start",
+      "stopCommand": "pkill -f 'node.*start'",
+      "restartCommand": null,
+      "dependencies": []
+    }
+  ],
+  "directories": ["subdirectory1", "subdirectory2"],
+  "metadata": {
+    "analyzedAt": "${new Date().toISOString()}",
+    "analyzedBy": "talk-to-code-agent",
+    "framework": "detected-framework",
+    "language": "javascript",
+    "packageManager": "npm"
+  }
+}
+
+CRITICAL INSTRUCTIONS:
+1. Output ONLY the JSON object, nothing else
+2. No markdown formatting, no code blocks, no explanations
+3. Use Read/Glob tools to examine the project structure thoroughly
+4. Extract actual port numbers, commands, and configurations from files
+5. startCommand is REQUIRED for each app - must be the actual command to start the app
+6. stopCommand and restartCommand are optional (can be null)
+7. appType MUST be "static-frontend" for React/Vue/Angular/Svelte/Next.js static builds, or "backend" for Express/Fastify/FastAPI/Django/etc.
+8. buildDir MUST be specified for static frontends (usually "dist", "build", or "public")
+9. port is REQUIRED for HTTP apps
+10. endpoints should be an array of HTTP routes (e.g., ["/", "/api", "/api/v1"])
+11. directory should be relative path from project root, empty string "" for root app
+12. Be thorough and accurate - identify ALL apps/services in the project
+13. Each app will get a TypeScript runner file ({appName}_runner.ts) generated automatically
+14. The runner will wrap the app to collect logs, stats, and provide unified control
+15. After generating the JSON, write it to ".claude-voice.json" file in the project root using the Write tool`
+
+  let config: ProjectConfig | null = null
+  let lastAssistantMessage = ''
+  let errorOccurred = false
+  let foundJson = false
+  const assistantMessages: string[] = []
+
+  try {
+    // Create temporary session handler
+    await agentSessionManager.createSession({
+      sessionId: analysisSessionId,
+      projectPath,
+      onOutput: (output: SessionOutput) => {
+        // Capture assistant messages to extract JSON
+        if (output.type === 'assistant') {
+          const data = typeof output.data === 'string' ? output.data : JSON.stringify(output.data)
+          assistantMessages.push(data)
+          lastAssistantMessage = data
+        }
+        // Check for file writes (Claude might write the JSON file directly)
+        if (output.type === 'tool_result' && output.metadata?.toolName === 'Write') {
+          const toolResult = output.metadata.toolResult
+          if (toolResult && typeof toolResult === 'object' && 'file_path' in toolResult) {
+            const filePath = (toolResult as any).file_path
+            if (filePath && filePath.includes('.talk-to-code.json')) {
+              // Claude wrote the config file, mark as found
+              foundJson = true
+            }
+          }
+        }
+        if (output.type === 'result' && output.metadata?.isError) {
+          errorOccurred = true
+        }
+      },
+      onError: (error) => {
+        console.error(`Analysis session error: ${error}`)
+        errorOccurred = true
+      },
+      onComplete: () => {
+        // Session completed
+      }
+    })
+
+    // Send analysis prompt
+    await agentSessionManager.sendPrompt(analysisSessionId, analysisPrompt, [], {
+      sessionId: analysisSessionId,
+      projectPath,
+      onOutput: (output: SessionOutput) => {
+        // Capture assistant messages
+        if (output.type === 'assistant') {
+          const data = typeof output.data === 'string' ? output.data : JSON.stringify(output.data)
+          assistantMessages.push(data)
+          lastAssistantMessage = data
+        }
+        // Also check for file writes (Claude might write the JSON file directly)
+        if (output.type === 'tool_result' && output.metadata?.toolName === 'Write') {
+          // Claude wrote a file, check if it's the config file
+          const toolResult = output.metadata.toolResult
+          if (toolResult && typeof toolResult === 'object' && 'file_path' in toolResult) {
+            const filePath = (toolResult as any).file_path
+            if (filePath && filePath.includes('.talk-to-code.json')) {
+              // Claude wrote the config file, try to read it
+              setTimeout(async () => {
+                try {
+                  const configPath = path.join(projectPath, '.talk-to-code.json')
+                  const content = await fs.readFile(configPath, 'utf-8')
+                  const parsed = JSON.parse(content) as ProjectConfig
+                  if (parsed && parsed.apps) {
+                    config = parsed
+                    foundJson = true
+                  }
+                } catch (error) {
+                  // Ignore read errors
+                }
+              }, 1000)
+            }
+          }
+        }
+      },
+      onError: (error: string) => {
+        console.error(`Analysis error: ${error}`)
+        errorOccurred = true
+      },
+      onComplete: () => {
+        // Analysis complete
+      }
+    })
+
+    // Wait for Claude to process (give it time to read files and generate response)
+    // Check multiple times as Claude may take a while - wait up to 90 seconds
+    const configFilePath = path.join(projectPath, CONFIG_FILENAME)
+    
+    for (let i = 0; i < 90; i++) {
+      await new Promise(resolve => setTimeout(resolve, 1000))
+      
+      // Check if Claude wrote the config file directly
+      try {
+        await fs.access(configFilePath)
+        const fileContent = await fs.readFile(configFilePath, 'utf-8')
+        const parsed = JSON.parse(fileContent) as ProjectConfig
+        if (parsed && parsed.apps) {
+          config = parsed
+          foundJson = true
+          break
+        }
+      } catch {
+        // File doesn't exist yet or invalid JSON, continue waiting
+      }
+      
+      // Check if we have a complete JSON response in messages
+      if (lastAssistantMessage && (lastAssistantMessage.includes('"version"') || lastAssistantMessage.includes('"apps"') || lastAssistantMessage.includes('"services"'))) {
+        foundJson = true
+        break
+      }
+      
+      // Check if session completed (result message received)
+      if (errorOccurred) {
+        break
+      }
+    }
+    
+    // If config was read from file, use it instead of parsing messages
+    if (!config || !foundJson) {
+      // Try to extract JSON from the assistant messages (check all messages, latest first)
+      for (let i = assistantMessages.length - 1; i >= 0; i--) {
+      let jsonStr = assistantMessages[i].trim()
+      
+      // Remove markdown code blocks if present
+      jsonStr = jsonStr.replace(/^```json\s*/i, '').replace(/^```\s*/, '').replace(/\s*```$/, '')
+      jsonStr = jsonStr.trim()
+      
+      // Try to extract JSON object if wrapped in text
+      const jsonMatch = jsonStr.match(/\{[\s\S]*\}/)
+      if (jsonMatch) {
+        jsonStr = jsonMatch[0]
+      }
+
+      try {
+        const parsedConfig = JSON.parse(jsonStr) as ProjectConfig
+        config = parsedConfig
+        foundJson = true
+        break
+      } catch (parseError: any) {
+        // Try next message
+        continue
+      }
+      }
+    }
+    
+    // Validate and ensure required fields if config was loaded
+    if (config && foundJson) {
+      // Validate and ensure required fields
+      if (!config.version) config.version = '1.0.0'
+      if (!config.projectName) config.projectName = projectName
+      if (!config.apps) config.apps = []
+      if (!config.directories) config.directories = []
+      
+      // Migrate old "services" to "apps" if present
+      if ((config as any).services && !config.apps) {
+        config.apps = (config as any).services
+      }
+      
+      // Ensure each app has a startCommand
+      config.apps = config.apps.map(app => ({
+        ...app,
+        startCommand: app.startCommand || 'echo "No start command configured"',
+      }))
+      
+      if (!config.metadata) {
+        config.metadata = {
+          analyzedAt: new Date().toISOString(),
+          analyzedBy: 'talk-to-code-agent'
+        }
+      } else {
+        config.metadata.analyzedAt = new Date().toISOString()
+        config.metadata.analyzedBy = 'talk-to-code-agent'
+      }
+    }
+
+    // Clean up session
+    try {
+      await agentSessionManager.deleteSession(analysisSessionId)
+    } catch (cleanupError) {
+      console.warn(`Failed to cleanup analysis session:`, cleanupError)
+    }
+
+  } catch (error: any) {
+    console.error(`Error during Claude analysis:`, error.message)
+    errorOccurred = true
+    
+    // Try to cleanup session
+    try {
+      await agentSessionManager.deleteSession(analysisSessionId)
+    } catch {}
+  }
+
+  // If analysis failed or no config extracted, throw error (caller can handle fallback)
+  if (!config || errorOccurred) {
+    throw new Error(`Claude analysis failed or incomplete. Last message: ${lastAssistantMessage.substring(0, 200)}`)
+  }
+  
+  return config
+}
+
+/**
+ * Read project configuration from file
+ */
+export async function getProjectConfig(projectPath: string): Promise<ProjectConfig | null> {
+  try {
+    const configPath = path.join(projectPath, CONFIG_FILENAME)
+    const content = await fs.readFile(configPath, 'utf-8')
+    const config = JSON.parse(content) as ProjectConfig
+    
+    // Migrate old "services" to "apps" if present
+    if ((config as any).services && !config.apps) {
+      config.apps = (config as any).services
+    }
+    
+    return config
+  } catch (error: any) {
+    if (error.code === 'ENOENT') {
+      return null // Config file doesn't exist yet
+    }
+    throw error
+  }
+}
+
+/**
+ * Save project configuration to file
+ */
+export async function saveProjectConfig(projectPath: string, config: ProjectConfig): Promise<void> {
+  const configPath = path.join(projectPath, CONFIG_FILENAME)
+  const content = JSON.stringify(config, null, 2)
+  await fs.writeFile(configPath, content, 'utf-8')
+}