@latentforce/shift 1.0.5 → 1.0.7

package/README.md

@@ -1,9 +1,6 @@
 # @latentforce/shift
 
-A CLI and MCP server for AI-powered code intelligence. It provides:
-
-1. **CLI commands** - Index and manage your project
-2. **MCP server** - Expose tools (blast_radius, dependencies, file_summary) to Claude Desktop/Code
+AI-powered code intelligence CLI and MCP server for Claude.
 
 ## Installation
 
@@ -13,191 +10,77 @@ npm install -g @latentforce/shift
 
 ## Quick Start
 
-### Step 1: Configure backend URLs (if using hosted service)
-
-If you're connecting to a hosted Shift backend (not localhost), configure the URLs first:
-
-```bash
-shift config set api-url https://dev-shift-lite.latentforce.ai
-shift config set orch-url https://agent-orch.latentforce.ai
-shift config set ws-url wss://agent-orch.latentforce.ai
-```
-
-### Step 2: Start and configure your project
+### 1. Initialize your project
 
 ```bash
 cd /path/to/your/project
-shift start
+shift-cli start    # Configure API key and project
+shift-cli init     # Index project files
 ```
 
-This will:
-- Prompt for your Shift API key or let you continue as guest
-- Let you select or enter your project ID
-- Start a background daemon that connects to the backend
-
-### Step 3: Index your project
+### 2. Add to Claude Code
 
 ```bash
-shift init
+claude mcp add-json shift '{"type":"stdio","command":"shift-cli","args":["mcp"],"env":{"SHIFT_PROJECT_ID":"YOUR_PROJECT_ID"}}'
 ```
 
-This scans your project files and sends the structure to the backend for indexing.
-
-### Step 4: Configure MCP for Claude
-
-Now Claude can use the MCP tools. See [Claude Desktop setup](#claude-desktop-setup) or [Claude Code setup](#claude-code-setup) below.
-
-## CLI Commands
-
-| 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 config` | Show/set configuration (URLs, API key) |
-| `shift` or `shift mcp` | Start MCP server on stdio (used by Claude) |
-
-## Authentication
-
-When running `shift start` or `shift init`, you'll be prompted to choose:
-
-1. **API Key** - Enter your Shift API key for full access
-2. **Guest Mode** - Continue without an API key (limited features)
-
-Both options work with all CLI commands. Your choice is saved to `~/.shift/config.json`.
-
-## MCP Tools
-
-The MCP server exposes these tools to Claude:
-
-| 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 |
-
-## Configuration
-
-### Using the Config Command (Recommended for Global Install)
-
-The easiest way to configure Shift after installing globally with `npm i -g @latentforce/shift`:
+Or using npx:
 
 ```bash
-# Show current configuration
-shift config
-
-# Set backend URLs
-shift config set api-url https://dev-shift-lite.latentforce.ai
-shift config set orch-url https://agent-orch.latentforce.ai
-shift config set ws-url wss://agent-orch.latentforce.ai
-
-# Set API key directly (alternative to interactive prompt)
-shift config set api-key your-api-key-here
-
-# Clear configuration
-shift config clear urls    # Reset URLs to defaults
-shift config clear         # Clear all config (prompts for confirmation)
+claude mcp add-json shift '{"type":"stdio","command":"npx","args":["@latentforce/shift","mcp"],"env":{"SHIFT_PROJECT_ID":"YOUR_PROJECT_ID"}}'
 ```
 
-Configuration is saved to `~/.shift/config.json`.
-
-### Using Environment Variables
-
-You can also set environment variables (they take priority over config file):
+### 3. Add to Claude Desktop
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `SHIFT_PROJECT_ID` | Default project UUID (MCP only) | - |
-| `SHIFT_BACKEND_URL` | Backend API URL (MCP only) | `http://127.0.0.1:9000` |
-
-Example using environment variables:
-
-```bash
-# Set for current session
-export SHIFT_API_URL=https://dev-shift-lite.latentforce.ai
-export SHIFT_ORCH_URL=https://agent-orch.latentforce.ai
-export SHIFT_WS_URL=wss://agent-orch.latentforce.ai
-
-# Or inline when running commands
-SHIFT_API_URL=https://dev-shift-lite.latentforce.ai shift start
-```
-
-### Priority Order
-
-URLs are resolved in this order:
-1. Environment variables (highest priority)
-2. Config file (`~/.shift/config.json`)
-3. Defaults (localhost)
-
-## Claude Code Setup
-
-### Add MCP Server
-
-```bash
-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"}}'
-```
-
-### Verify
-
-```bash
-claude mcp list
-```
-
-## 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:
+Add to your config file (`%APPDATA%\Claude\claude_desktop_config.json` on Windows, `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
 
 ```json
 {
   "mcpServers": {
     "shift": {
-      "command": "shift",
+      "command": "shift-cli",
+      "args": ["mcp"],
       "env": {
-        "SHIFT_BACKEND_URL": "https://dev-shift-lite.latentforce.ai",
-        "SHIFT_PROJECT_ID": "YOUR_PROJECT_ID_HERE"
+        "SHIFT_PROJECT_ID": "YOUR_PROJECT_ID"
       }
     }
   }
 }
 ```
 
-Restart Claude Desktop after saving.
+## MCP Tools
 
-## Project ID
+| Tool | Description |
+|------|-------------|
+| `blast_radius` | Analyze what would be affected if a file is modified |
+| `dependencies` | Get all dependencies for a file |
+| `file_summary` | Generate a summary of a file |
 
-You can set the project ID in two ways:
+## CLI Commands
 
-1. **Environment variable**: Set `SHIFT_PROJECT_ID` in MCP config
-2. **Per-call override**: Pass `project_id` parameter in each tool call
+| Command | Description |
+|---------|-------------|
+| `shift-cli start` | Start daemon and configure project |
+| `shift-cli init` | Index project files |
+| `shift-cli stop` | Stop the daemon |
+| `shift-cli status` | Show current status |
+| `shift-cli config` | Manage configuration |
 
-This allows one MCP server to work with multiple projects.
+## Custom Backend URLs
 
-## Development
+**CLI** (set once globally):
 
 ```bash
-# Clone and install
-npm install
-
-# Build
-npm run build
+shift-cli config set api-url https://your-api.example.com
+shift-cli config set orch-url https://your-orch.example.com
+shift-cli config set ws-url wss://your-orch.example.com
+```
 
-# Run locally
-node build/index.js
+**MCP Server** (add to env in Claude config):
 
-# Test CLI commands
-node build/index.js start
-node build/index.js init
-node build/index.js status
-node build/index.js stop
+```json
+"env": {
+  "SHIFT_PROJECT_ID": "YOUR_PROJECT_ID",
+  "SHIFT_BACKEND_URL": "https://your-api.example.com"
+}
 ```

package/build/cli/commands/init.js

@@ -1,13 +1,29 @@
 import { exec } from 'child_process';
 import { promisify } from 'util';
+import { createInterface } from 'readline';
 import { getApiKey, setApiKey, setGuestKey, isGuestKey, readProjectConfig, writeProjectConfig } from '../../utils/config.js';
 import { promptApiKey, promptKeyChoice } from '../../utils/prompts.js';
-import { requestGuestKey } from '../../utils/api-client.js';
+import { requestGuestKey, fetchProjectStatus } from '../../utils/api-client.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() {
+/**
+ * Prompt user to confirm re-indexing an already indexed project
+ */
+async function promptForReindex() {
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question('Do you want to re-index the project? (y/N): ', (answer) => {
+            rl.close();
+            resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+        });
+    });
+}
+export async function initCommand(options = {}) {
     const projectRoot = process.cwd();
     console.log('╔═══════════════════════════════════════════════╗');
     console.log('║         Initializing Shift Project            ║');
@@ -51,6 +67,32 @@ export async function initCommand() {
         process.exit(1);
     }
     console.log(`[Init] ✓ Project: ${projectConfig.project_name} (${projectConfig.project_id})\n`);
+    // Check if project is already indexed (skip check if --force flag is used)
+    if (!options.force) {
+        try {
+            const projectStatus = await fetchProjectStatus(apiKey, projectConfig.project_id);
+            if (projectStatus.indexed) {
+                console.log(`[Init] ✓ Project already indexed (${projectStatus.file_count} files)\n`);
+                const shouldReindex = await promptForReindex();
+                if (!shouldReindex) {
+                    console.log('\n╔═══════════════════════════════════════════════╗');
+                    console.log('║         Project Already Initialized           ║');
+                    console.log('╚═══════════════════════════════════════════════╝');
+                    console.log('\nUse "shift status" to check the current status.');
+                    console.log('Use "shift init --force" to force re-indexing.\n');
+                    return;
+                }
+                console.log('\n[Init] Proceeding with re-indexing...\n');
+            }
+        }
+        catch {
+            // If we can't check status, continue with init (server might be unavailable)
+            console.log('[Init] ⚠️  Could not check indexing status, proceeding with initialization...\n');
+        }
+    }
+    else {
+        console.log('[Init] Force flag detected, skipping indexing status check...\n');
+    }
     // Step 3: Check daemon status (warn if not running)
     console.log('[Init] Step 3/5: Checking daemon status...');
     const status = getDaemonStatus(projectRoot);

package/build/cli/commands/status.js

@@ -1,5 +1,6 @@
 import { getApiKey, readProjectConfig, isGuestKey } from '../../utils/config.js';
 import { getDaemonStatus } from '../../daemon/daemon-manager.js';
+import { fetchProjectStatus } from '../../utils/api-client.js';
 export async function statusCommand() {
     const projectRoot = process.cwd();
     console.log('\n╔════════════════════════════════════════════╗');
@@ -34,6 +35,20 @@ export async function statusCommand() {
             console.log(`             - ${agent.agent_name} (${agent.agent_type})`);
         });
     }
+    // Check project indexing status (work done)
+    try {
+        const projectStatus = await fetchProjectStatus(apiKey, projectConfig.project_id);
+        if (projectStatus.indexed) {
+            console.log(`Indexed:     ✓ Complete (${projectStatus.file_count} files)`);
+        }
+        else {
+            console.log('Indexed:     ❌ Not indexed');
+            console.log('             Run "shift-cli init" to scan the project.');
+        }
+    }
+    catch {
+        console.log('Indexed:     ⚠️  Unable to check (server unavailable)');
+    }
     // Check daemon status
     const status = getDaemonStatus(projectRoot);
     if (!status.running) {

package/build/index.js

@@ -2,14 +2,21 @@
 import { Command } from 'commander';
 const program = new Command();
 program
-    .name('shift')
+    .name('shift-cli')
     .description('Shift CLI - AI-powered code intelligence')
-    .version('1.0.2');
+    .version('1.0.6');
 // MCP server mode (default when run via MCP host)
 program
     .command('mcp', { isDefault: true, hidden: true })
     .description('Start MCP server on stdio')
     .action(async () => {
+    // Check if 'mcp' was explicitly passed as argument
+    const mcpExplicitlyRequested = process.argv.includes('mcp');
+    // If running interactively (TTY) and mcp wasn't explicitly requested, show help
+    if (process.stdin.isTTY && !mcpExplicitlyRequested) {
+        program.outputHelp();
+        return;
+    }
     const { startMcpServer } = await import('./mcp-server.js');
     await startMcpServer();
 });
@@ -24,9 +31,10 @@ program
 program
     .command('init')
     .description('Initialize and scan the project for file indexing')
-    .action(async () => {
+    .option('-f, --force', 'Force re-indexing even if project is already indexed')
+    .action(async (options) => {
     const { initCommand } = await import('./cli/commands/init.js');
-    await initCommand();
+    await initCommand({ force: options.force ?? false });
 });
 program
     .command('stop')

package/build/mcp-server.js

@@ -1,7 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from 'zod';
-const BASE_URL = process.env.SHIFT_BACKEND_URL || "http://127.0.0.1:9000";
+const BASE_URL = process.env.SHIFT_BACKEND_URL || "https://dev-shift-lite.latentforce.ai";
 function getProjectIdFromEnv() {
     const projectId = process.env.SHIFT_PROJECT_ID;
     if (!projectId || projectId.trim() === "") {

package/build/utils/api-client.js

@@ -1,13 +1,23 @@
 import { API_BASE_URL, API_BASE_URL_ORCH } from './config.js';
+import { getMachineFingerprint } from './machine-id.js';
 /**
- * Request a guest API key
+ * Request a guest API key bound to this machine
+ * The backend will:
+ * - Create a new guest key if this machine_id hasn't been seen before
+ * - Return the existing guest key if this machine_id already has one
+ * - Optionally enforce usage limits per machine
  */
 export async function requestGuestKey() {
+    const fingerprint = getMachineFingerprint();
     const response = await fetch(`${API_BASE_URL}/api/guest-key`, {
         method: 'POST',
         headers: {
             'Content-Type': 'application/json',
         },
+        body: JSON.stringify({
+            machine_id: fingerprint.machine_id,
+            platform: fingerprint.platform,
+        }),
     });
     if (!response.ok) {
         const text = await response.text();
@@ -64,3 +74,30 @@ export async function sendInitScan(apiKey, projectId, payload) {
         throw error;
     }
 }
+/**
+ * Fetch project indexing/work status
+ * Returns whether the knowledge graph has been built for this project
+ */
+export async function fetchProjectStatus(apiKey, projectId) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 5000); // 5 second timeout
+    try {
+        const response = await fetch(`${API_BASE_URL}/api/projects/${projectId}/status`, {
+            method: 'GET',
+            headers: {
+                'Authorization': `Bearer ${apiKey}`,
+            },
+            signal: controller.signal,
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(text || `HTTP ${response.status}`);
+        }
+        return await response.json();
+    }
+    catch (error) {
+        clearTimeout(timeoutId);
+        throw error;
+    }
+}

package/build/utils/machine-id.js

@@ -0,0 +1,46 @@
+import os from 'os';
+import crypto from 'crypto';
+/**
+ * Get the primary MAC address (first non-internal interface)
+ */
+function getPrimaryMacAddress() {
+    const interfaces = os.networkInterfaces();
+    for (const [name, addrs] of Object.entries(interfaces)) {
+        if (!addrs)
+            continue;
+        for (const addr of addrs) {
+            // Skip internal/loopback and addresses without MAC
+            if (addr.internal || !addr.mac || addr.mac === '00:00:00:00:00:00') {
+                continue;
+            }
+            return addr.mac;
+        }
+    }
+    return 'unknown';
+}
+/**
+ * Generate a unique, deterministic machine fingerprint
+ * Uses MAC address + platform for stability
+ * - MAC is globally unique per network interface
+ * - Platform helps distinguish dual-boot scenarios
+ */
+export function generateMachineId() {
+    const mac = getPrimaryMacAddress();
+    const platform = os.platform();
+    // Combine MAC + platform
+    const fingerprintData = `${mac}|${platform}`;
+    // Hash for privacy and fixed length
+    return crypto.createHash('sha256').update(fingerprintData).digest('hex');
+}
+/**
+ * Generate a shorter machine ID (first 16 chars of full hash)
+ */
+export function generateShortMachineId() {
+    return generateMachineId().substring(0, 16);
+}
+export function getMachineFingerprint() {
+    return {
+        machine_id: generateMachineId(),
+        platform: os.platform(),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@latentforce/shift",
-    "version": "1.0.5",
+    "version": "1.0.7",
     "description": "Shift CLI - AI-powered code intelligence with MCP support",
     "type": "module",
     "main": "./build/index.js",
@@ -8,7 +8,7 @@
         ".": "./build/index.js"
     },
     "bin": {
-        "shift": "./build/index.js"
+        "shift-cli": "./build/index.js"
     },
     "files": [
         "build"