@latentforce/shift 1.0.0 → 1.0.2

package/README.md

@@ -1,103 +1,108 @@
-# shift-mcp
+# @latentforce/shift
 
-A minimal utility server built for the Model Context Protocol (MCP). It exposes tools that call the Shift Lite webapp backend for file summary, dependencies, and blast radius (using the project's knowledge graph).
+A CLI and MCP server for AI-powered code intelligence. It provides:
 
-## Environment variables
-
-- **`SHIFT_PROJECT_ID`** (optional if you pass per call): The default Shift Lite project UUID. If set, all tools use this project unless overridden by the `project_id` parameter in a tool call.
-  - Example: `export SHIFT_PROJECT_ID=9af16a19-d073-4134-a0cd-272b0baf912e`
-- **`SHIFT_BACKEND_URL`** (optional): Webapp backend base URL. Default: `http://127.0.0.1:9000`.
-
-## Project ID: env vs per-call
-
-- **Default:** Set `SHIFT_PROJECT_ID` in the MCP config (or env). All tools use that project.
-- **Override per call:** Each tool (`blast_radius`, `dependencies`, `file_summary`) accepts an optional **`project_id`** parameter. If you pass it, that call uses that project; otherwise the tool uses `SHIFT_PROJECT_ID`. So you can use one MCP for multiple projects by passing `project_id` in the call (e.g. "blast radius for project abc-123").
+1. **CLI commands** - Index and manage your project
+2. **MCP server** - Expose tools (blast_radius, dependencies, file_summary) to Claude Desktop/Code
 
 ## Installation
 
-### Option 1: Install globally (simple, persistent)
-
 ```bash
 npm install -g @latentforce/shift
 ```
 
-Verify it works:
+## Quick Start
+
+### Step 1: Start and configure your project
+
 ```bash
-shift
+cd /path/to/your/project
+shift start
 ```
 
-You should see:
+This will:
+- Prompt for your Shift API key (saved to `~/.shift/config.json`)
+- Let you select or enter your project ID
+- Start a background daemon that connects to the backend
+
+### Step 2: Index your project
+
 ```bash
-Shift-lite MCP Server running on stdio
+shift init
 ```
 
+This scans your project files and sends the structure to the backend for indexing.
 
-## Claude Code setup
+### Step 3: Configure MCP for Claude
 
-Claude Code does not auto-discover MCP servers. You must register it manually.
+Now Claude can use the MCP tools. See [Claude Desktop setup](#claude-desktop-setup) or [Claude Code setup](#claude-code-setup) below.
 
-### Install the Package (if not already)
-You can use this package without installing it globally by using npx, or install it globally for faster access.
+## CLI Commands
 
-```bash
-npm install -g @latentforce/shift
-```
+| Command | Description |
+|---------|-------------|
+| `shift start` | Start the daemon and configure the project |
+| `shift init` | Scan and index project files to backend |
+| `shift stop` | Stop the running daemon |
+| `shift status` | Show current status (API key, project, daemon, connection) |
+| `shift` or `shift mcp` | Start MCP server on stdio (used by Claude) |
 
-### Add to Claude Code
-- Replace SHIFT_BACKEND_URL and SHIFT_PROJECT_ID with correct values.
-- SHIFT_PROJECT_ID may be ignored as every tool accepts an optional **`project_id`** parameter.
-For Windows Users
-```bash
-claude mcp add --scope user --transport stdio --env SHIFT_BACKEND_URL=BACKEND_URL --env SHIFT_PROJECT_ID=9af16a19-d073-4134-a0cd-272b0baf912e shift -- cmd /c npx -y @latentforce/shift
-```
+## MCP Tools
 
-For macOS/Linux Users
-```bash
-claude mcp add --scope user --transport stdio --env SHIFT_BACKEND_URL=BACKEND_URL --env SHIFT_PROJECT_ID=9af16a19-d073-4134-a0cd-272b0baf912e shift -- npx -y @latentforce/shift
-```
+The MCP server exposes these tools to Claude:
 
-### Verify Installation
-```bash
-claude mcp list
-```
+| Tool | Description |
+|------|-------------|
+| `blast_radius` | Analyze what would be affected if a file is modified |
+| `dependencies` | Get all dependencies for a file (direct and transitive) |
+| `file_summary` | Generate a summary of a file with optional parent context |
 
-### Use It
-Start a Claude Code session:
-```bash
-claude
-```
+## Environment Variables
 
-## Claude Desktop setup
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SHIFT_PROJECT_ID` | Default project UUID (can be overridden per tool call) | - |
+| `SHIFT_BACKEND_URL` | Backend API URL | `http://127.0.0.1:9000` |
+| `SHIFT_API_URL` | API URL for CLI | `http://localhost:9000` |
+| `SHIFT_ORCH_URL` | Orchestrator URL | `http://localhost:9999` |
+| `SHIFT_WS_URL` | WebSocket URL | `ws://localhost:9999` |
 
-Claude Desktop does not auto-discover MCP servers. You must register it manually.
+## Claude Code Setup
 
-### Config file location
+### Add MCP Server
 
-**macOS (Claude Desktop app):**
 ```bash
-~/Library/Application Support/Claude/claude_desktop_config.json
+claude mcp add-json shift '{"type":"stdio","command":"shift","args":[],"env":{"SHIFT_PROJECT_ID":"YOUR_PROJECT_ID_HERE","SHIFT_BACKEND_URL":"https://dev-shift-lite.latentforce.ai"}}'
 ```
-*(In Claude Desktop: Claude menu → Settings… → Developer → Edit Config)*
 
-**Linux (if different):**
-```bash
-~/.config/claude-desktop/claude_desktop_config.json
-```
+### Verify
 
-**Windows:**
 ```bash
-%APPDATA%\Claude\claude_desktop_config.json
+claude mcp list
 ```
 
-Add this (replace `YOUR_PROJECT_UUID` with your Shift Lite project ID):
+## Claude Desktop Setup
+
+### Config File Location
+
+| OS | Path |
+|----|------|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Linux | `~/.config/claude-desktop/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+
+### Configuration
+
+Add to your config file:
+
 ```json
 {
   "mcpServers": {
     "shift": {
       "command": "shift",
       "env": {
-        "SHIFT_BACKEND_URL": "BACKEND URL",
-        "SHIFT_PROJECT_ID": "YOUR_PROJECT_UUID"
+        "SHIFT_BACKEND_URL": "https://dev-shift-lite.latentforce.ai",
+        "SHIFT_PROJECT_ID": "YOUR_PROJECT_ID_HERE"
       }
     }
   }
@@ -106,16 +111,55 @@ Add this (replace `YOUR_PROJECT_UUID` with your Shift Lite project ID):
 
 Restart Claude Desktop after saving.
 
+## Project ID
+
+You can set the project ID in two ways:
+
+1. **Environment variable**: Set `SHIFT_PROJECT_ID` in MCP config
+2. **Per-call override**: Pass `project_id` parameter in each tool call
+
+This allows one MCP server to work with multiple projects.
+
 ## Development
 
-Clone and build:
 ```bash
+# Clone and install
 npm install
+
+# Build
 npm run build
-```
 
-Run locally:
-```bash
+# Run locally
 node build/index.js
+
+# Test CLI commands
+node build/index.js start
+node build/index.js init
+node build/index.js status
+node build/index.js stop
 ```
 
+## How It All Works Together
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        User's Machine                           │
+│                                                                 │
+│  ┌─────────────┐     ┌─────────────┐     ┌─────────────────┐   │
+│  │ shift start │────▶│   Daemon    │────▶│ Backend (WS)    │   │
+│  │ shift init  │     │ (background)│     │                 │   │
+│  │ shift stop  │     └─────────────┘     │                 │   │
+│  │ shift status│                         │                 │   │
+│  └─────────────┘                         │   Shift Lite    │   │
+│                                          │   Backend       │   │
+│  ┌─────────────┐     ┌─────────────┐     │                 │   │
+│  │   Claude    │────▶│ shift (MCP) │────▶│ (REST API)      │   │
+│  │ Desktop/Code│     │   Server    │     │                 │   │
+│  └─────────────┘     └─────────────┘     └─────────────────┘   │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+
+1. `shift start` - Starts daemon, connects to backend via WebSocket
+2. `shift init`  - Indexes project files to backend
+3. Claude calls MCP tools - MCP server queries backend REST API
+```

package/build/cli/commands/init.js

@@ -0,0 +1,136 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { getApiKey, setApiKey, readProjectConfig, writeProjectConfig } from '../../utils/config.js';
+import { promptApiKey } from '../../utils/prompts.js';
+import { getDaemonStatus } from '../../daemon/daemon-manager.js';
+import { getProjectTree, extractAllFilePaths, categorizeFiles } from '../../utils/tree-scanner.js';
+import { sendInitScan } from '../../utils/api-client.js';
+const execAsync = promisify(exec);
+export async function initCommand() {
+    const projectRoot = process.cwd();
+    console.log('╔═══════════════════════════════════════════════╗');
+    console.log('║         Initializing Shift Project            ║');
+    console.log('╚═══════════════════════════════════════════════╝\n');
+    // Step 1: Check API key
+    console.log('[Init] Step 1/5: Checking API key...');
+    let apiKey = getApiKey();
+    if (!apiKey) {
+        apiKey = await promptApiKey();
+        setApiKey(apiKey);
+        console.log('[Init] ✓ API key saved\n');
+    }
+    else {
+        console.log('[Init] ✓ API key found\n');
+    }
+    // Step 2: Check project config
+    console.log('[Init] Step 2/5: Checking project configuration...');
+    const projectConfig = readProjectConfig(projectRoot);
+    if (!projectConfig) {
+        console.error('\n❌ No project configured for this directory.');
+        console.log('Run "shift start" first to configure the project.\n');
+        process.exit(1);
+    }
+    console.log(`[Init] ✓ Project: ${projectConfig.project_name} (${projectConfig.project_id})\n`);
+    // Step 3: Check daemon status (warn if not running)
+    console.log('[Init] Step 3/5: Checking daemon status...');
+    const status = getDaemonStatus(projectRoot);
+    if (!status.running) {
+        console.log('[Init] ⚠️  Warning: Daemon is not running. Run "shift start" to start it.\n');
+    }
+    else {
+        console.log(`[Init] ✓ Daemon running (PID: ${status.pid}, Connected: ${status.connected})\n`);
+    }
+    // Step 4: Scan project structure (matching extension's Step 6)
+    console.log('[Init] Step 4/5: Scanning project structure...');
+    // Get project tree (matching extension's getProjectTree)
+    const treeData = getProjectTree(projectRoot, {
+        depth: 0, // Unlimited depth
+        exclude_patterns: [
+            '.git',
+            'node_modules',
+            '__pycache__',
+            '.vscode',
+            'dist',
+            'build',
+            '.shift',
+            '.next',
+            'coverage',
+            'venv',
+            'env',
+        ],
+    });
+    console.log(`[Init]   Files: ${treeData.file_count}`);
+    console.log(`[Init]   Directories: ${treeData.dir_count}`);
+    console.log(`[Init]   Total size: ${treeData.total_size_mb} MB\n`);
+    // Get git info (matching extension)
+    let gitInfo = {
+        current_branch: '',
+        original_branch: 'shift_original',
+        migrate_branch: 'shift_migrated',
+        has_uncommitted_changes: false,
+    };
+    try {
+        const { stdout: currentBranch } = await execAsync('git branch --show-current', { cwd: projectRoot });
+        const { stdout: statusOutput } = await execAsync('git status --porcelain', { cwd: projectRoot });
+        gitInfo.current_branch = currentBranch.trim();
+        gitInfo.has_uncommitted_changes = statusOutput.trim().length > 0;
+        console.log(`[Init] ✓ Git info: branch=${gitInfo.current_branch}, uncommitted=${gitInfo.has_uncommitted_changes}\n`);
+    }
+    catch {
+        console.log('[Init] ⚠️  Not a git repository or git not available\n');
+    }
+    // Extract file paths and categorize (matching extension)
+    const allFiles = extractAllFilePaths(treeData.tree);
+    const categorized = categorizeFiles(treeData.tree);
+    console.log(`[Init]   Source files: ${categorized.source_files.length}`);
+    console.log(`[Init]   Config files: ${categorized.config_files.length}`);
+    console.log(`[Init]   Asset files: ${categorized.asset_files.length}\n`);
+    // Step 5: Send scan to backend (matching extension's Step 9)
+    console.log('[Init] Step 5/5: Sending scan to backend...');
+    const payload = {
+        project_id: projectConfig.project_id,
+        project_tree: treeData,
+        git_info: gitInfo,
+        file_manifest: {
+            all_files: allFiles,
+            categorized: categorized,
+        },
+        metadata: {
+            extension_version: '1.0.2-cli', // CLI version
+            scan_timestamp: new Date().toISOString(),
+            project_name: projectConfig.project_name,
+        },
+    };
+    try {
+        const response = await sendInitScan(apiKey, projectConfig.project_id, payload);
+        console.log('[Init] ✓ Backend initialization completed');
+        console.log(`[Init]   Files read: ${response.files_read}`);
+        console.log(`[Init]   Files failed: ${response.files_failed}`);
+        // Update local config with agent info (matching extension)
+        if (response.agents_created?.theme_planner) {
+            const agentInfo = {
+                agent_id: response.agents_created.theme_planner.agent_id,
+                agent_name: response.agents_created.theme_planner.agent_name,
+                agent_type: 'theme_planner',
+                created_at: new Date().toISOString(),
+            };
+            projectConfig.agents = projectConfig.agents || [];
+            projectConfig.agents.push(agentInfo);
+            writeProjectConfig(projectConfig, projectRoot);
+            console.log(`[Init] ✓ Agent info saved: ${agentInfo.agent_id}`);
+        }
+        console.log('\n╔═══════════════════════════════════════════════╗');
+        console.log('║       ✓ Project Initialization Complete       ║');
+        console.log('╚═══════════════════════════════════════════════╝');
+        if (response.next_steps) {
+            console.log('\nNext steps:');
+            response.next_steps.forEach((step) => console.log(`  - ${step}`));
+        }
+        console.log('\nFile indexing has been triggered. This may take a few moments.');
+        console.log('Use "shift status" to check the daemon connection.\n');
+    }
+    catch (error) {
+        console.error(`\n❌ Failed to initialize project: ${error.message}`);
+        process.exit(1);
+    }
+}

package/build/cli/commands/start.js

@@ -0,0 +1,81 @@
+import { getApiKey, setApiKey, setProject, readProjectConfig } from '../../utils/config.js';
+import { promptApiKey, promptProjectId, promptSelectProject } from '../../utils/prompts.js';
+import { startDaemon, getDaemonStatus } from '../../daemon/daemon-manager.js';
+import { fetchProjects } from '../../utils/api-client.js';
+export async function startCommand() {
+    const projectRoot = process.cwd();
+    console.log('╔════════════════════════════════════════════╗');
+    console.log('║         Starting Shift                     ║');
+    console.log('╚════════════════════════════════════════════╝\n');
+    // Step 1: Ensure API key exists
+    console.log('[Start] Step 1/4: Checking API key...');
+    let apiKey = getApiKey();
+    if (!apiKey) {
+        apiKey = await promptApiKey();
+        setApiKey(apiKey);
+        console.log('[Start] ✓ API key saved to ~/.shift/config.json\n');
+    }
+    else {
+        console.log('[Start] ✓ API key found\n');
+    }
+    // Step 2: Check/create project config
+    console.log('[Start] Step 2/4: Checking project configuration...');
+    let projectConfig = readProjectConfig(projectRoot);
+    if (!projectConfig) {
+        // Fetch available projects
+        console.log('[Start] Fetching your projects...');
+        try {
+            const projects = await fetchProjects(apiKey);
+            if (!projects || projects.length === 0) {
+                console.error('\n❌ No projects found. Create one in the Shift dashboard first.');
+                process.exit(1);
+            }
+            console.log(`[Start] Found ${projects.length} project(s)\n`);
+            // Let user select a project
+            const selected = await promptSelectProject(projects);
+            // Save project config (matching extension's .shift/config.json structure)
+            setProject(selected.project_id, selected.project_name, projectRoot);
+            console.log(`[Start] ✓ Project "${selected.project_name}" saved to .shift/config.json\n`);
+            projectConfig = readProjectConfig(projectRoot);
+        }
+        catch (error) {
+            // If fetching fails, fall back to manual entry
+            console.error(`\n⚠️  Could not fetch projects: ${error.message}`);
+            console.log('Falling back to manual project ID entry...\n');
+            const projectId = await promptProjectId();
+            setProject(projectId, 'Unknown Project', projectRoot);
+            console.log(`[Start] ✓ Project ID saved to .shift/config.json\n`);
+            projectConfig = readProjectConfig(projectRoot);
+        }
+    }
+    else {
+        console.log(`[Start] ✓ Project found: ${projectConfig.project_name} (${projectConfig.project_id})\n`);
+    }
+    if (!projectConfig) {
+        console.error('❌ Failed to configure project');
+        process.exit(1);
+    }
+    // Step 3: Check if daemon is already running
+    console.log('[Start] Step 3/4: Checking daemon status...');
+    const status = getDaemonStatus(projectRoot);
+    if (status.running) {
+        console.log(`[Start] ✓ Daemon is already running (PID: ${status.pid})`);
+        console.log(`[Start]   WebSocket: ${status.connected ? 'Connected' : 'Connecting...'}\n`);
+        return;
+    }
+    console.log('[Start] Daemon not running\n');
+    // Step 4: Start daemon
+    console.log('[Start] Step 4/4: Starting daemon...');
+    const result = await startDaemon(projectRoot, projectConfig.project_id, apiKey);
+    if (!result.success) {
+        console.error(`\n❌ Failed to start daemon: ${result.error}`);
+        process.exit(1);
+    }
+    console.log(`[Start] ✓ Daemon started (PID: ${result.pid})`);
+    console.log('\n╔════════════════════════════════════════════╗');
+    console.log('║         Shift is now running!              ║');
+    console.log('╚════════════════════════════════════════════╝');
+    console.log('\nUse "shift status" to check connection status.');
+    console.log('Use "shift init" to scan and index the project.');
+    console.log('Use "shift stop" to stop the daemon.\n');
+}

package/build/cli/commands/status.js

@@ -0,0 +1,46 @@
+import { getApiKey, readProjectConfig } from '../../utils/config.js';
+import { getDaemonStatus } from '../../daemon/daemon-manager.js';
+export async function statusCommand() {
+    const projectRoot = process.cwd();
+    console.log('\n╔════════════════════════════════════════════╗');
+    console.log('║              Shift Status                  ║');
+    console.log('╚════════════════════════════════════════════╝\n');
+    // Check API key
+    const apiKey = getApiKey();
+    if (!apiKey) {
+        console.log('API Key:     ❌ Not configured');
+        console.log('\nRun "shift start" to configure your API key.\n');
+        return;
+    }
+    console.log('API Key:     ✓ Configured');
+    // Check project config
+    const projectConfig = readProjectConfig(projectRoot);
+    if (!projectConfig) {
+        console.log('Project:     ❌ Not configured');
+        console.log('\nRun "shift start" to configure this project.\n');
+        return;
+    }
+    console.log(`Project:     ${projectConfig.project_name}`);
+    console.log(`Project ID:  ${projectConfig.project_id}`);
+    // Check agents
+    if (projectConfig.agents && projectConfig.agents.length > 0) {
+        console.log(`Agents:      ${projectConfig.agents.length} configured`);
+        projectConfig.agents.forEach((agent) => {
+            console.log(`             - ${agent.agent_name} (${agent.agent_type})`);
+        });
+    }
+    // Check daemon status
+    const status = getDaemonStatus(projectRoot);
+    if (!status.running) {
+        console.log('Daemon:      ❌ Not running');
+        console.log('\nRun "shift start" to start the daemon.\n');
+        return;
+    }
+    console.log(`Daemon:      ✓ Running (PID: ${status.pid})`);
+    console.log(`WebSocket:   ${status.connected ? '✓ Connected' : '⚠️  Disconnected'}`);
+    if (status.startedAt) {
+        const startedAt = new Date(status.startedAt);
+        console.log(`Started:     ${startedAt.toLocaleString()}`);
+    }
+    console.log('');
+}

package/build/cli/commands/stop.js

@@ -0,0 +1,18 @@
+import { getDaemonStatus, stopDaemon } from '../../daemon/daemon-manager.js';
+export async function stopCommand() {
+    const projectRoot = process.cwd();
+    console.log('\nStopping Shift daemon...\n');
+    // Check if daemon is running
+    const status = getDaemonStatus(projectRoot);
+    if (!status.running) {
+        console.log('Daemon is not running.');
+        return;
+    }
+    console.log(`Stopping daemon (PID: ${status.pid})...`);
+    const result = await stopDaemon(projectRoot);
+    if (!result.success) {
+        console.error(`Failed to stop daemon: ${result.error}`);
+        process.exit(1);
+    }
+    console.log('Daemon stopped successfully.\n');
+}

package/build/daemon/daemon-manager.js

@@ -0,0 +1,136 @@
+import { spawn } from 'child_process';
+import * as path from 'path';
+import * as fs from 'fs';
+import { fileURLToPath } from 'url';
+import { readDaemonPid, writeDaemonPid, removeDaemonPid, removeDaemonStatus, readDaemonStatus, isProcessRunning, } from '../utils/config.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+function getDaemonScriptPath() {
+    // The daemon.js will be in the same directory as daemon-manager.js after compilation
+    return path.join(__dirname, 'daemon.js');
+}
+export async function startDaemon(projectRoot, projectId, apiKey) {
+    // Check if daemon is already running
+    const existingPid = readDaemonPid(projectRoot);
+    if (existingPid && isProcessRunning(existingPid)) {
+        return {
+            success: false,
+            error: `Daemon already running with PID ${existingPid}`,
+            pid: existingPid,
+        };
+    }
+    // Clean up stale files if process is not running
+    if (existingPid) {
+        removeDaemonPid(projectRoot);
+        removeDaemonStatus(projectRoot);
+    }
+    const daemonScript = getDaemonScriptPath();
+    if (!fs.existsSync(daemonScript)) {
+        return {
+            success: false,
+            error: `Daemon script not found at ${daemonScript}`,
+        };
+    }
+    try {
+        // Spawn detached daemon process
+        const child = spawn(process.execPath, [daemonScript, projectRoot, projectId, apiKey], {
+            detached: true,
+            stdio: 'ignore',
+            cwd: projectRoot,
+        });
+        if (!child.pid) {
+            return {
+                success: false,
+                error: 'Failed to spawn daemon process',
+            };
+        }
+        // Detach from parent
+        child.unref();
+        // Write PID file
+        writeDaemonPid(child.pid, projectRoot);
+        return {
+            success: true,
+            pid: child.pid,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to start daemon: ${error.message}`,
+        };
+    }
+}
+export async function stopDaemon(projectRoot) {
+    const pid = readDaemonPid(projectRoot);
+    if (!pid) {
+        return {
+            success: false,
+            error: 'No daemon PID file found',
+        };
+    }
+    if (!isProcessRunning(pid)) {
+        // Clean up stale files
+        removeDaemonPid(projectRoot);
+        removeDaemonStatus(projectRoot);
+        return {
+            success: true,
+        };
+    }
+    try {
+        // Send SIGTERM for graceful shutdown
+        process.kill(pid, 'SIGTERM');
+        // Wait for process to exit (with timeout)
+        const maxWait = 5000;
+        const checkInterval = 100;
+        let waited = 0;
+        while (waited < maxWait && isProcessRunning(pid)) {
+            await new Promise((resolve) => setTimeout(resolve, checkInterval));
+            waited += checkInterval;
+        }
+        // If still running, force kill
+        if (isProcessRunning(pid)) {
+            try {
+                process.kill(pid, 'SIGKILL');
+            }
+            catch {
+                // Process might have exited between check and kill
+            }
+        }
+        // Clean up files
+        removeDaemonPid(projectRoot);
+        removeDaemonStatus(projectRoot);
+        return {
+            success: true,
+        };
+    }
+    catch (error) {
+        // Clean up files even on error
+        removeDaemonPid(projectRoot);
+        removeDaemonStatus(projectRoot);
+        return {
+            success: false,
+            error: `Failed to stop daemon: ${error.message}`,
+        };
+    }
+}
+export function getDaemonStatus(projectRoot) {
+    const pid = readDaemonPid(projectRoot);
+    const status = readDaemonStatus(projectRoot);
+    if (!pid) {
+        return { running: false };
+    }
+    const running = isProcessRunning(pid);
+    if (!running) {
+        // Clean up stale files
+        removeDaemonPid(projectRoot);
+        removeDaemonStatus(projectRoot);
+        return { running: false };
+    }
+    return {
+        running: true,
+        pid,
+        connected: status?.connected ?? false,
+        projectId: status?.project_id,
+        startedAt: status?.started_at,
+    };
+}