@latentforce/shift 1.0.9 → 1.0.11

package/README.md

@@ -2,12 +2,16 @@
 
 AI-powered code intelligence CLI and MCP server for Claude.
 
+Shift indexes your codebase, builds a dependency relationship graph (DRG), and provides AI-powered insights via MCP tools — enabling Claude to understand your project's structure, dependencies, and blast radius of changes.
+
 ## Installation
 
 ```bash
 npm install -g @latentforce/shift
 ```
 
+Requires Node.js >= 18.
+
 ## Quick Start
 
 ### Guest mode (zero-config)
@@ -34,19 +38,27 @@ shift-cli start    # Configure API key and project interactively
 shift-cli init     # Index project files
 ```
 
-### Add to Claude Code
+## MCP Integration
+
+After initializing your project, use `shift-cli add` to configure Shift's MCP server in your AI coding tool:
 
 ```bash
-claude mcp add-json shift '{"type":"stdio","command":"shift-cli","args":["mcp"],"env":{"SHIFT_PROJECT_ID":"YOUR_PROJECT_ID"}}'
+shift-cli add <tool>
 ```
 
-Or using npx:
+### Supported tools
 
-```bash
-claude mcp add-json shift '{"type":"stdio","command":"npx","args":["@latentforce/shift","mcp"],"env":{"SHIFT_PROJECT_ID":"YOUR_PROJECT_ID"}}'
-```
+| Tool | Command | Config method |
+|------|---------|---------------|
+| Claude Code | `shift-cli add claude-code` | Runs `claude mcp add-json` |
+| Opencode | `shift-cli add opencode` | Writes `opencode.json` |
+| Codex | `shift-cli add codex` | Runs `codex mcp add` |
+| GitHub Copilot | `shift-cli add copilot` | Writes `.vscode/mcp.json` |
+| Factory Droid | `shift-cli add droid` | Runs `droid mcp add` |
+
+For CLI-based tools, if the CLI is not installed, the command will print manual setup instructions.
 
-### Add to Claude Desktop
+### Claude Desktop (manual)
 
 Add to your config file (`%APPDATA%\Claude\claude_desktop_config.json` on Windows, `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
 
@@ -68,52 +80,179 @@ Add to your config file (`%APPDATA%\Claude\claude_desktop_config.json` on Window
 
 | Command | Description |
 |---------|-------------|
-| `shift-cli start` | Start daemon and configure project |
+| `shift-cli start` | Start the daemon and configure the project |
 | `shift-cli init` | Scan and index project files |
 | `shift-cli update-drg` | Update the dependency relationship graph |
+| `shift-cli add <tool>` | Add Shift MCP server to an AI coding tool |
 | `shift-cli stop` | Stop the daemon |
 | `shift-cli status` | Show current status |
 | `shift-cli config` | Manage configuration |
 
-### CLI Flags
+### `shift-cli init`
+
+Performs a full project scan — collects the file tree, categorizes files (source, config, assets), gathers git info, and sends everything to the Shift backend for indexing. Automatically starts the daemon if not running.
 
-#### `shift-cli init`
+If the project is already indexed, you will be prompted to re-index. Use `--force` to skip the prompt.
 
 | Flag | Description |
 |------|-------------|
-| `--guest` | Use guest authentication (auto-creates project) |
+| `--guest` | Use guest authentication (auto-creates a temporary project) |
 | `--api-key <key>` | Provide API key directly |
 | `--project-name <name>` | Create new project or match existing by name |
 | `--project-id <id>` | Use existing project UUID |
 | `--template <id>` | Migration template ID for project creation |
 | `-f, --force` | Force re-indexing even if already indexed |
 
-#### `shift-cli start`
+```bash
+shift-cli init                     # Interactive initialization
+shift-cli init --force             # Force re-index without prompt
+shift-cli init --guest             # Quick init with guest auth
+```
+
+### `shift-cli start`
+
+Resolves authentication, configures the project, and launches a background daemon that maintains a WebSocket connection to the Shift backend.
 
 | Flag | Description |
 |------|-------------|
-| `--guest` | Use guest authentication (auto-creates project) |
+| `--guest` | Use guest authentication (auto-creates a temporary project) |
 | `--api-key <key>` | Provide API key directly |
 | `--project-name <name>` | Create new project or match existing by name |
 | `--project-id <id>` | Use existing project UUID |
 | `--template <id>` | Migration template ID for project creation |
 
-#### `shift-cli update-drg`
+```bash
+shift-cli start                                     # Interactive setup
+shift-cli start --guest                              # Quick start without API key
+shift-cli start --api-key <key> --project-name "My App"
+```
+
+### `shift-cli update-drg`
+
+Scans JavaScript/TypeScript files (`.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`), detects git changes, and sends file contents to the backend for dependency analysis.
 
 | Flag | Description |
 |------|-------------|
 | `-m, --mode <mode>` | `baseline` (all files) or `incremental` (git-changed only, default) |
 
-### Update DRG
+**Modes:**
+- **incremental** (default) — sends only git-changed files for faster updates
+- **baseline** — sends all JS/TS files for a full re-analysis
+
+```bash
+shift-cli update-drg                       # Incremental update (default)
+shift-cli update-drg -m baseline           # Full re-analysis
+```
+
+### `shift-cli add <tool>`
 
-After initializing your project, update the dependency graph to keep code intelligence in sync:
+Configures Shift's MCP server in the specified AI coding tool. Reads `project_id` from `.shift/config.json` (run `shift-cli init` first).
 
 ```bash
-shift-cli update-drg                    # Incremental (default) — only git-changed files
-shift-cli update-drg --mode baseline    # Full re-scan of all JS/TS files
+shift-cli add claude-code      # Configure via Claude Code CLI
+shift-cli add opencode         # Write to opencode.json
+shift-cli add codex            # Configure via Codex CLI
+shift-cli add copilot          # Write to .vscode/mcp.json
+shift-cli add droid    # Configure via Droid CLI
 ```
 
-Scans `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs` files.
+### `shift-cli config`
+
+Manage Shift configuration (URLs, API key).
+
+| Action | Description |
+|--------|-------------|
+| `show` | Display current configuration (default) |
+| `set <key> <value>` | Set a configuration value |
+| `clear [key]` | Clear a specific key or all configuration |
+
+**Configurable keys:** `api-key`, `api-url`, `orch-url`, `ws-url`
+
+URLs can also be set via environment variables: `SHIFT_API_URL`, `SHIFT_ORCH_URL`, `SHIFT_WS_URL`.
+
+```bash
+shift-cli config                                      # Show config
+shift-cli config set api-key sk-abc123                 # Set API key
+shift-cli config set api-url https://api.shift.ai      # Set API URL
+shift-cli config clear api-key                         # Clear API key
+shift-cli config clear                                 # Clear all config
+```
+
+## `.shiftignore`
+
+Shift uses a `.shiftignore` file to control which files and directories are excluded from indexing and dependency analysis. It follows the same syntax as `.gitignore`.
+
+A default `.shiftignore` is **automatically created** the first time you run `shift-cli init` or `shift-cli start`. You can edit it to customize which files are excluded.
+
+### Syntax
+
+- Blank lines are ignored
+- Lines starting with `#` are comments
+- Standard glob patterns (`*`, `**`, `?`)
+- Trailing `/` matches directories only
+- Leading `/` anchors to the project root
+- `!` negates a pattern (re-includes a previously ignored path)
+
+### Default `.shiftignore`
+
+The auto-generated file excludes common non-source directories and files:
+
+```gitignore
+# Dependencies
+node_modules/
+vendor/
+bower_components/
+
+# Build output
+dist/
+build/
+out/
+.next/
+
+# Test & coverage
+coverage/
+.nyc_output/
+
+# Environment & secrets
+.env
+.env.*
+*.pem
+*.key
+
+# Logs
+*.log
+logs/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Python
+__pycache__/
+*.pyc
+venv/
+.venv/
+
+# Misc
+*.min.js
+*.min.css
+*.map
+```
+
+### Bypassing `.shiftignore`
+
+Use the `--no-ignore` flag to skip `.shiftignore` rules for a single run:
+
+```bash
+shift-cli init --no-ignore         # Index all files
+shift-cli update-drg --no-ignore   # Include ignored files in DRG update
+```
 
 ## MCP Tools
 
@@ -125,6 +264,10 @@ Scans `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs` files.
 
 Each tool accepts an optional `project_id` parameter. If not provided, it falls back to the `SHIFT_PROJECT_ID` environment variable.
 
-MCP tools return formatted markdown and include:
-- **Path normalization** — backslashes, leading `./` and `/` are handled automatically
-- **Actionable error messages** — missing graph prompts you to run `update-drg`, missing files explain possible causes
+## Configuration Files
+
+| File | Location | Description |
+|------|----------|-------------|
+| Global config | `~/.shift/config.json` | API key and server URLs |
+| Project config | `.shift/config.json` | Project ID, name, and agent info |
+| Ignore rules | `.shiftignore` | Files/directories to exclude (auto-created) |

package/build/cli/commands/add.js

@@ -0,0 +1,209 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import * as fs from 'fs';
+import * as path from 'path';
+import { getProjectId } from '../../utils/config.js';
+const execAsync = promisify(exec);
+const SUPPORTED_TOOLS = ['claude-code', 'opencode', 'codex', 'copilot', 'droid'];
+function isNotFound(e) {
+    return e.code === 'ENOENT' || /ENOENT|not found|not recognized/.test(e.message);
+}
+function getStderr(e) {
+    return (e.stderr || e.message || '').trim();
+}
+function shellEscape(arg) {
+    if (/^[a-zA-Z0-9._\-=/]+$/.test(arg))
+        return arg;
+    return `"${arg.replace(/"/g, '\\"')}"`;
+}
+function buildCommand(bin, args) {
+    return [bin, ...args.map(shellEscape)].join(' ');
+}
+function getMcpConfig(projectId) {
+    return {
+        command: 'shift-cli',
+        args: ['mcp'],
+        env: { SHIFT_PROJECT_ID: projectId },
+    };
+}
+async function addClaudeCode(projectId) {
+    const jsonPayload = JSON.stringify({
+        type: 'stdio',
+        command: 'shift-cli',
+        args: ['mcp'],
+        env: { SHIFT_PROJECT_ID: projectId },
+    });
+    try {
+        await execAsync(buildCommand('claude', ['mcp', 'add-json', 'shift', jsonPayload]));
+        console.log('  Added Shift MCP server to Claude Code.');
+        console.log('\n  Verify with: claude mcp list');
+    }
+    catch (e) {
+        const err = e;
+        const stderr = getStderr(err);
+        if (/already exists/.test(stderr)) {
+            console.log('  Shift MCP server is already configured in Claude Code.');
+            console.log('  To update, remove it first: claude mcp remove shift');
+        }
+        else if (isNotFound(err)) {
+            console.log('  "claude" CLI not found. Add manually:\n');
+            console.log(`  claude mcp add-json shift '${jsonPayload}'`);
+        }
+        else {
+            console.log(`  Failed: ${stderr}`);
+            console.log('\n  Try adding manually:\n');
+            console.log(`  claude mcp add-json shift '${jsonPayload}'`);
+        }
+    }
+}
+async function addCodex(projectId) {
+    const config = getMcpConfig(projectId);
+    const args = ['mcp', 'add', 'shift'];
+    for (const [k, v] of Object.entries(config.env)) {
+        args.push('--env', `${k}=${v}`);
+    }
+    args.push('--', config.command, ...config.args);
+    const manualCmd = `codex ${args.join(' ')}`;
+    try {
+        await execAsync(buildCommand('codex', args));
+        console.log('  Added Shift MCP server to Codex.');
+        console.log('\n  Verify with: codex mcp list');
+    }
+    catch (e) {
+        const err = e;
+        const stderr = getStderr(err);
+        if (isNotFound(err)) {
+            console.log('  "codex" CLI not found. Make sure Codex CLI is installed and on your PATH.\n');
+            console.log('  Once installed, add manually:\n');
+        }
+        else if (/already exists/.test(stderr)) {
+            console.log('  Shift MCP server is already configured in Codex.');
+            console.log('  To update, remove it first: codex mcp remove shift');
+            return;
+        }
+        else {
+            console.log(`  Failed: ${stderr}`);
+            console.log('\n  Try adding manually:\n');
+        }
+        console.log(`  ${manualCmd}`);
+    }
+}
+async function addFactoryDroid(projectId) {
+    const config = getMcpConfig(projectId);
+    const args = ['mcp', 'add', 'shift', config.command];
+    for (const [k, v] of Object.entries(config.env)) {
+        args.push('--env', `${k}=${v}`);
+    }
+    const manualCmd = `droid ${args.join(' ')}`;
+    try {
+        await execAsync(buildCommand('droid', args));
+        console.log('  Added Shift MCP server to Factory Droid.');
+        console.log('\n  Verify: type /mcp within droid to see configured servers');
+    }
+    catch (e) {
+        const err = e;
+        console.log(`  Failed: ${getStderr(err)}`);
+        console.log('\n  Try adding manually:\n');
+        console.log(`  ${manualCmd}`);
+    }
+}
+function mergeJsonConfig(filePath, serverKey, serverValue) {
+    let config = {};
+    if (fs.existsSync(filePath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+        }
+        catch {
+            console.log(`  Warning: Could not parse existing ${filePath}, creating new file.`);
+            config = {};
+        }
+    }
+    // Navigate/create nested keys
+    let obj = config;
+    for (let i = 0; i < serverKey.length - 1; i++) {
+        const key = serverKey[i];
+        if (typeof obj[key] !== 'object' || obj[key] === null) {
+            obj[key] = {};
+        }
+        obj = obj[key];
+    }
+    const finalKey = serverKey[serverKey.length - 1];
+    obj[finalKey] = serverValue;
+    // Ensure parent directory exists
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n');
+}
+function addOpencode(projectId, projectRoot) {
+    const filePath = path.join(projectRoot, 'opencode.json');
+    let existing = {};
+    if (fs.existsSync(filePath)) {
+        try {
+            existing = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+        }
+        catch { /* will be recreated */ }
+    }
+    if (!existing['$schema']) {
+        existing['$schema'] = 'https://opencode.ai/config.json';
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(filePath, JSON.stringify(existing, null, 2) + '\n');
+    }
+    mergeJsonConfig(filePath, ['mcp', 'shift'], {
+        type: 'local',
+        command: ["shift-cli", "mcp"],
+        enabled: true,
+        environment: { "SHIFT_PROJECT_ID": projectId },
+    });
+    console.log(`  Updated ${filePath}`);
+    console.log('\n  Verify: check "mcp.shift" in opencode.json');
+}
+function addCopilot(projectId, projectRoot) {
+    const config = getMcpConfig(projectId);
+    const filePath = path.join(projectRoot, '.vscode', 'mcp.json');
+    mergeJsonConfig(filePath, ['servers', 'shift'], {
+        command: config.command,
+        args: config.args,
+        env: config.env,
+    });
+    console.log(`  Updated ${filePath}`);
+    console.log('\n  Verify: check "servers.shift" in .vscode/mcp.json');
+}
+export async function addCommand(tool) {
+    if (!SUPPORTED_TOOLS.includes(tool)) {
+        console.error(`\n  Unknown tool: "${tool}"\n`);
+        console.error('  Supported tools:');
+        for (const t of SUPPORTED_TOOLS) {
+            console.error(`    - ${t}`);
+        }
+        process.exit(1);
+    }
+    const projectRoot = process.cwd();
+    const projectId = getProjectId(projectRoot);
+    if (!projectId) {
+        console.error('\n  No project configured. Run "shift-cli init" first to set up your project.\n');
+        process.exit(1);
+    }
+    console.log(`\n  Configuring Shift MCP for ${tool}...\n`);
+    switch (tool) {
+        case 'claude-code':
+            await addClaudeCode(projectId);
+            break;
+        case 'opencode':
+            addOpencode(projectId, projectRoot);
+            break;
+        case 'codex':
+            await addCodex(projectId);
+            break;
+        case 'copilot':
+            addCopilot(projectId, projectRoot);
+            break;
+        case 'droid':
+            await addFactoryDroid(projectId);
+            break;
+    }
+    console.log('');
+}

package/build/cli/commands/init.js

@@ -2,11 +2,13 @@ import { exec } from 'child_process';
 import { promisify } from 'util';
 import { createInterface } from 'readline';
 import { createRequire } from 'module';
-import { readProjectConfig, writeProjectConfig } from '../../utils/config.js';
+import { existsSync, readFileSync } from 'fs';
+import path from 'path';
+import { readProjectConfig, writeProjectConfig, ensureScanTargetFile } from '../../utils/config.js';
 import { fetchProjectStatus, sendInitScan } from '../../utils/api-client.js';
 import { resolveApiKey, resolveProject } from '../../utils/auth-resolver.js';
 import { getDaemonStatus, startDaemon } from '../../daemon/daemon-manager.js';
-import { getProjectTree, extractAllFilePaths, categorizeFiles } from '../../utils/tree-scanner.js';
+import { getProjectTree, extractAllFilePaths, categorizeFiles, countProjectLOC } from '../../utils/tree-scanner.js';
 const require = createRequire(import.meta.url);
 const { version } = require('../../../package.json');
 const execAsync = promisify(exec);
@@ -63,6 +65,8 @@ export async function initCommand(options = {}) {
         console.error('\n❌ Failed to configure project.');
         process.exit(1);
     }
+    // Ensure .shift/scan_target.json exists (template for user customization)
+    ensureScanTargetFile(projectRoot);
     // Check if project is already indexed (skip check if --force flag is used)
     if (!options.force) {
         try {
@@ -160,11 +164,49 @@ export async function initCommand(options = {}) {
     // Extract file paths and categorize (matching extension)
     const allFiles = extractAllFilePaths(treeData.tree);
     const categorized = categorizeFiles(treeData.tree);
+    // Count total lines of code
+    const totalLOC = countProjectLOC(projectRoot, allFiles);
+    console.log(`[Init] Total LOC: ${totalLOC}`);
     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...');
+    // Read scan targets from .shift/scan_target.json if it exists
+    let scanTargets = null;
+    const scanTargetPath = path.join(projectRoot, '.shift', 'scan_target.json');
+    if (existsSync(scanTargetPath)) {
+        try {
+            const raw = readFileSync(scanTargetPath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            // Accept both array format and single object format
+            const targets = Array.isArray(parsed) ? parsed : [parsed];
+            const mapped = targets.map((t) => ({
+                language: t.language ?? t.lang ?? null,
+                path: t.path ?? '',
+            }));
+            // Treat default template (single entry with language=null, path="") as unconfigured
+            const isDefault = mapped.length === 1 && mapped[0].language === null && mapped[0].path === '';
+            if (isDefault) {
+                console.log('[Init] .shift/scan_target.json is default template — server will auto-detect scan targets');
+                console.log('[Init]   Edit the file to manually specify scan targets');
+            }
+            else {
+                scanTargets = mapped;
+                console.log(`[Init] ✓ Loaded ${scanTargets.length} scan target(s) from .shift/scan_target.json`);
+                for (const t of scanTargets) {
+                    console.log(`[Init]   → language=${t.language ?? 'auto'}, path="${t.path || '(root)'}"`);
+                }
+            }
+        }
+        catch (err) {
+            console.log(`[Init] ⚠️  Failed to read .shift/scan_target.json: ${err.message}`);
+            console.log('[Init]   Proceeding without scan targets (server will auto-detect)');
+        }
+    }
+    else {
+        console.log('[Init] No .shift/scan_target.json found — server will auto-detect scan targets');
+    }
     const payload = {
         project_id: project.projectId,
         project_tree: treeData,
@@ -178,6 +220,8 @@ export async function initCommand(options = {}) {
             scan_timestamp: new Date().toISOString(),
             project_name: project.projectName,
         },
+        scan_targets: scanTargets,
+        total_loc: totalLOC,
     };
     try {
         const response = await sendInitScan(apiKey, project.projectId, payload);

package/build/cli/commands/start.js

@@ -1,4 +1,4 @@
-import { readProjectConfig, setProject } from '../../utils/config.js';
+import { readProjectConfig, setProject, ensureScanTargetFile } from '../../utils/config.js';
 import { startDaemon, getDaemonStatus } from '../../daemon/daemon-manager.js';
 import { resolveApiKey, resolveProject } from '../../utils/auth-resolver.js';
 export async function startCommand(options = {}) {
@@ -37,6 +37,8 @@ export async function startCommand(options = {}) {
         console.error('❌ Failed to configure project');
         process.exit(1);
     }
+    // Ensure .shift/scan_target.json exists (template for user customization)
+    ensureScanTargetFile(projectRoot);
     // Step 3: Check if daemon is already running
     console.log('[Start] Step 3/4: Checking daemon status...');
     const status = getDaemonStatus(projectRoot);

package/build/cli/commands/update-drg.js

@@ -9,7 +9,7 @@ const execAsync = promisify(exec);
 async function detectGitChanges(projectRoot, extensions) {
     const changes = { added: [], modified: [], deleted: [] };
     try {
-        const { stdout } = await execAsync('git status --porcelain', { cwd: projectRoot });
+        const { stdout } = await execAsync('git status --porcelain -u', { cwd: projectRoot });
         for (const line of stdout.split('\n')) {
             if (!line.trim())
                 continue;
@@ -51,7 +51,24 @@ async function detectGitChanges(projectRoot, extensions) {
     }
     return changes;
 }
-const JS_TS_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs']);
+const LANGUAGE_CONFIG = {
+    js_ts: {
+        extensions: new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs']),
+        label: 'JS/TS',
+    },
+    python: {
+        extensions: new Set(['.py']),
+        label: 'Python',
+    },
+    csharp: {
+        extensions: new Set(['.cs']),
+        label: 'C#',
+    },
+    cpp: {
+        extensions: new Set(['.cpp', '.cc', '.cxx', '.h', '.hpp', '.c']),
+        label: 'C/C++',
+    },
+};
 export async function updateDrgCommand(options = {}) {
     const projectRoot = process.cwd();
     const mode = options.mode || 'incremental';
@@ -75,8 +92,8 @@ export async function updateDrgCommand(options = {}) {
         process.exit(1);
     }
     console.log(`[DRG] ✓ Project: ${projectConfig.project_name} (${projectConfig.project_id})\n`);
-    // Step 3: Scan project for JS/TS files
-    console.log('[DRG] Step 3/4: Scanning project for JS/TS files...');
+    // Step 3: Scan project for all supported language files
+    console.log('[DRG] Step 3/4: Scanning project for supported languages...');
     const treeData = getProjectTree(projectRoot, {
         depth: 0,
         exclude_patterns: [
@@ -94,82 +111,84 @@ export async function updateDrgCommand(options = {}) {
         ],
     });
     const allFiles = extractAllFilePaths(treeData.tree);
-    const jstsFiles = allFiles.filter((filePath) => {
-        const ext = path.extname(filePath).toLowerCase();
-        return JS_TS_EXTENSIONS.has(ext);
-    });
+    // Group files by language (each file counted in first matching language)
+    const filesByLanguage = {};
+    for (const lang of Object.keys(LANGUAGE_CONFIG)) {
+        const extSet = LANGUAGE_CONFIG[lang].extensions;
+        filesByLanguage[lang] = allFiles.filter((filePath) => extSet.has(path.extname(filePath).toLowerCase()));
+    }
+    const languagesWithFiles = Object.entries(filesByLanguage).filter(([_, files]) => files.length > 0);
     console.log(`[DRG]   Total files scanned: ${allFiles.length}`);
-    console.log(`[DRG]   JS/TS files found: ${jstsFiles.length}\n`);
-    if (jstsFiles.length === 0) {
-        console.log('⚠️  No JS/TS files found in project. Nothing to update.\n');
+    for (const [lang, files] of languagesWithFiles) {
+        console.log(`[DRG]   ${LANGUAGE_CONFIG[lang].label} files: ${files.length}`);
+    }
+    console.log('');
+    if (languagesWithFiles.length === 0) {
+        console.log('⚠️  No supported language files found (JS/TS, Python, C#, C++). Nothing to update.\n');
         return;
     }
-    // Read file contents
-    const files = [];
-    let readErrors = 0;
-    for (const filePath of jstsFiles) {
-        const absolutePath = path.join(projectRoot, filePath);
-        try {
-            const content = fs.readFileSync(absolutePath, 'utf-8');
-            files.push({ file_path: filePath, content });
+    let anySent = false;
+    let lastError = null;
+    for (const [language, langFiles] of languagesWithFiles) {
+        const extSet = LANGUAGE_CONFIG[language].extensions;
+        const label = LANGUAGE_CONFIG[language].label;
+        // Read file contents for this language
+        const files = [];
+        let readErrors = 0;
+        for (const filePath of langFiles) {
+            const absolutePath = path.join(projectRoot, filePath);
+            try {
+                const content = fs.readFileSync(absolutePath, 'utf-8');
+                files.push({ file_path: filePath, content });
+            }
+            catch {
+                readErrors++;
+            }
         }
-        catch {
-            readErrors++;
+        if (readErrors > 0) {
+            console.log(`[DRG]   [${label}] ⚠️  Could not read ${readErrors} file(s)\n`);
         }
-    }
-    if (readErrors > 0) {
-        console.log(`[DRG] ⚠️  Could not read ${readErrors} file(s)\n`);
-    }
-    // Always use git to compute added/modified/deleted (single source of truth)
-    console.log('[DRG]   Detecting git changes...');
-    const gitChanges = await detectGitChanges(projectRoot, JS_TS_EXTENSIONS);
-    console.log(`[DRG]   Git changes — added: ${gitChanges.added.length}, modified: ${gitChanges.modified.length}, deleted: ${gitChanges.deleted.length}`);
-    // Which files to send: incremental = only changed; baseline = all (full re-analysis)
-    const changedPaths = new Set([...gitChanges.added, ...gitChanges.modified]);
-    const filesToSend = mode === 'baseline'
-        ? files
-        : files.filter((f) => changedPaths.has(f.file_path));
-    if (mode === 'baseline') {
-        console.log(`[DRG]   Baseline: sending all ${filesToSend.length} JS/TS files.\n`);
-    }
-    else {
-        console.log(`[DRG]   Incremental: sending ${filesToSend.length} changed file(s).\n`);
-    }
-    if (filesToSend.length === 0 && gitChanges.deleted.length === 0) {
-        console.log('\n✓ No JS/TS changes detected. DRG is up to date.\n');
-        return;
-    }
-    // Step 4: Send to backend
-    console.log(`[DRG] Step 4/4: Sending ${filesToSend.length} files to backend (mode: ${mode})...`);
-    const payload = {
-        project_id: projectConfig.project_id,
-        language: 'js_ts',
-        mode: mode,
-        changes: gitChanges,
-        files: filesToSend,
-    };
-    try {
-        const response = await sendUpdateDrg(apiKey, payload);
-        console.log('\n╔═══════════════════════════════════════════════╗');
-        console.log('║         ✓ DRG Update Complete                 ║');
-        console.log('╚═══════════════════════════════════════════════╝\n');
-        console.log(`  Success:    ${response.success}`);
-        console.log(`  Message:    ${response.message}`);
-        if (response.stats) {
-            console.log(`  Files sent: ${response.stats.total_files_provided}`);
-            console.log(`  Unique:     ${response.stats.unique_paths}`);
-            console.log(`  Added:      ${response.stats.added}`);
-            console.log(`  Modified:   ${response.stats.modified}`);
-            console.log(`  Deleted:    ${response.stats.deleted}`);
-            const affected = response.stats.affected_file_paths;
-            if (affected?.length) {
-                console.log(`  Affected by deletions (edges updated): ${affected.length} file(s)`);
+        const gitChanges = await detectGitChanges(projectRoot, extSet);
+        const changedPaths = new Set([...gitChanges.added, ...gitChanges.modified]);
+        const filesToSend = mode === 'baseline'
+            ? files
+            : files.filter((f) => changedPaths.has(f.file_path));
+        if (filesToSend.length === 0 && gitChanges.deleted.length === 0) {
+            console.log(`[DRG]   [${label}] No changes. Skipping.\n`);
+            continue;
+        }
+        console.log(`[DRG]   [${label}] Git changes — added: ${gitChanges.added.length}, modified: ${gitChanges.modified.length}, deleted: ${gitChanges.deleted.length}`);
+        console.log(`[DRG]   [${label}] Sending ${filesToSend.length} file(s) (mode: ${mode})...`);
+        const payload = {
+            project_id: projectConfig.project_id,
+            language,
+            mode,
+            changes: gitChanges,
+            files: filesToSend,
+        };
+        try {
+            const response = await sendUpdateDrg(apiKey, payload);
+            anySent = true;
+            console.log(`[DRG]   [${label}] ✓ ${response.message}`);
+            if (response.stats) {
+                console.log(`[DRG]   [${label}]   Files sent: ${response.stats.total_files_provided}, Added: ${response.stats.added}, Modified: ${response.stats.modified}, Deleted: ${response.stats.deleted}`);
             }
         }
-        console.log('\nUse "shift-cli status" to check progress.\n');
+        catch (error) {
+            lastError = error;
+            console.error(`[DRG]   [${label}] ❌ ${error.message}`);
+        }
+        console.log('');
     }
-    catch (error) {
-        console.error(`\n❌ Failed to update DRG: ${error.message}`);
+    // Step 4: Summary
+    console.log('╔═══════════════════════════════════════════════╗');
+    console.log('║         ✓ DRG Update Complete                 ║');
+    console.log('╚═══════════════════════════════════════════════╝\n');
+    if (lastError && !anySent) {
+        console.error(`❌ All updates failed. Last error: ${lastError.message}`);
         process.exit(1);
     }
+    if (lastError) {
+        console.log(`⚠️  Some languages failed (see above).`);
+    }
 }

package/build/index.js

@@ -6,16 +6,24 @@ const { version } = require('../package.json');
 const program = new Command();
 program
     .name('shift-cli')
-    .description('Shift CLI - AI-powered code intelligence')
+    .description('Shift CLI - AI-powered code intelligence and dependency analysis.\n\n' +
+    'Shift indexes your codebase, builds a dependency relationship graph (DRG),\n' +
+    'and provides AI-powered insights via MCP tools.\n\n' +
+    'Quick start:\n' +
+    '  shift-cli start          Start the daemon and configure project\n' +
+    '  shift-cli init           Scan and index the project\n' +
+    '  shift-cli update-drg     Build/update the dependency graph\n' +
+    '  shift-cli status         Check current status\n\n' +
+    'Configuration:\n' +
+    '  Global config:   ~/.shift/config.json\n' +
+    '  Project config:  .shift/config.json')
     .version(version);
 // 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;
@@ -23,15 +31,15 @@ program
     const { startMcpServer } = await import('./mcp-server.js');
     await startMcpServer();
 });
-// CLI commands
-program
+// --- start ---
+const startCmd = program
     .command('start')
     .description('Start the Shift daemon for this project')
-    .option('--guest', 'Use guest authentication (auto-creates project)')
-    .option('--api-key <key>', 'Provide API key directly')
-    .option('--project-name <name>', 'Create new project or match existing by name')
-    .option('--project-id <id>', 'Use existing project UUID')
-    .option('--template <id>', 'Migration template ID for project creation')
+    .option('--guest', 'Use guest authentication (auto-creates a temporary project)')
+    .option('--api-key <key>', 'Provide your Shift API key directly instead of interactive prompt')
+    .option('--project-name <name>', 'Create a new project or match an existing one by name')
+    .option('--project-id <id>', 'Link to an existing project by its UUID')
+    .option('--template <id>', 'Use a specific migration template when creating the project')
     .action(async (options) => {
     const { startCommand } = await import('./cli/commands/start.js');
     await startCommand({
@@ -42,15 +50,27 @@ program
         template: options.template,
     });
 });
-program
+startCmd.addHelpText('after', `
+Details:
+  Resolves authentication, configures the project, and launches a
+  background daemon that maintains a WebSocket connection to the
+  Shift backend.
+
+Examples:
+  shift-cli start                                   Interactive setup
+  shift-cli start --guest                            Quick start without API key
+  shift-cli start --api-key <key> --project-name "My App"
+`);
+// --- init ---
+const initCmd = program
     .command('init')
     .description('Initialize and scan the project for file indexing')
-    .option('-f, --force', 'Force re-indexing even if project is already indexed')
-    .option('--guest', 'Use guest authentication (auto-creates project)')
-    .option('--api-key <key>', 'Provide API key directly')
-    .option('--project-name <name>', 'Create new project or match existing by name')
-    .option('--project-id <id>', 'Use existing project UUID')
-    .option('--template <id>', 'Migration template ID for project creation')
+    .option('-f, --force', 'Force re-indexing even if the project is already indexed')
+    .option('--guest', 'Use guest authentication (auto-creates a temporary project)')
+    .option('--api-key <key>', 'Provide your Shift API key directly instead of interactive prompt')
+    .option('--project-name <name>', 'Create a new project or match an existing one by name')
+    .option('--project-id <id>', 'Link to an existing project by its UUID')
+    .option('--template <id>', 'Use a specific migration template when creating the project')
     .action(async (options) => {
     const { initCommand } = await import('./cli/commands/init.js');
     await initCommand({
@@ -62,33 +82,122 @@ program
         template: options.template,
     });
 });
-program
+initCmd.addHelpText('after', `
+Details:
+  Performs a full project scan — collects the file tree, categorizes files
+  (source, config, assets), gathers git info, and sends everything to the
+  Shift backend for indexing. Automatically starts the daemon if not running.
+
+  If the project is already indexed, you will be prompted to re-index.
+  Use --force to skip the prompt.
+
+Examples:
+  shift-cli init                     Interactive initialization
+  shift-cli init --force             Force re-index without prompt
+  shift-cli init --guest             Quick init with guest auth
+`);
+// --- stop ---
+const stopCmd = program
     .command('stop')
-    .description('Stop the Shift daemon')
+    .description('Stop the Shift daemon for this project')
     .action(async () => {
     const { stopCommand } = await import('./cli/commands/stop.js');
     await stopCommand();
 });
-program
+stopCmd.addHelpText('after', `
+Details:
+  Terminates the background daemon process. The daemon can be
+  restarted later with "shift-cli start".
+`);
+// --- status ---
+const statusCmd = program
     .command('status')
     .description('Show the current Shift status')
     .action(async () => {
     const { statusCommand } = await import('./cli/commands/status.js');
     await statusCommand();
 });
-program
+statusCmd.addHelpText('after', `
+Details:
+  Displays a comprehensive overview of:
+    - API key configuration (guest or authenticated)
+    - Project details (name, ID)
+    - Registered agents
+    - Backend indexing status and file count
+    - Daemon process status (PID, WebSocket connection, uptime)
+`);
+// --- update-drg ---
+const updateDrgCmd = program
     .command('update-drg')
-    .description('Update the dependency relationship graph (DRG) for this project')
-    .option('-m, --mode <mode>', 'Update mode: baseline (all files) or incremental (git-changed only)', 'incremental')
+    .description('Update the dependency relationship graph (DRG)')
+    .option('-m, --mode <mode>', 'Update mode: "baseline" (all files) or "incremental" (git-changed only)', 'incremental')
     .action(async (options) => {
     const { updateDrgCommand } = await import('./cli/commands/update-drg.js');
     await updateDrgCommand({ mode: options.mode });
 });
-program
+updateDrgCmd.addHelpText('after', `
+Details:
+  Scans JavaScript/TypeScript files (.js, .jsx, .ts, .tsx, .mjs, .cjs),
+  detects git changes, and sends file contents to the backend for
+  dependency analysis.
+
+Modes:
+  incremental    Send only git-changed files (default, faster)
+  baseline       Send all JS/TS files (full re-analysis)
+
+Examples:
+  shift-cli update-drg                       Incremental update
+  shift-cli update-drg -m baseline           Full re-analysis
+`);
+// --- add mcp servers---
+const addCmd = program
+    .command('add <tool>')
+    .description('Add Shift MCP server to an AI coding tool')
+    .action(async (tool) => {
+    const { addCommand } = await import('./cli/commands/add.js');
+    await addCommand(tool);
+});
+addCmd.addHelpText('after', `
+Supported tools:
+  claude-code     Configure via Claude Code CLI
+  opencode        Write to opencode.json
+  codex           Configure via Codex CLI
+  copilot         Write to .vscode/mcp.json
+  droid           Configure via Factory-Droid CLI
+
+Examples:
+  shift-cli add claude-code
+  shift-cli add copilot
+  shift-cli add opencode
+`);
+// --- config ---
+const configCmd = program
     .command('config [action] [key] [value]')
     .description('Manage Shift configuration (URLs, API key)')
     .action(async (action, key, value) => {
     const { configCommand } = await import('./cli/commands/config.js');
     await configCommand(action, key, value);
 });
+configCmd.addHelpText('after', `
+Actions:
+  show              Display current configuration (default)
+  set <key> <val>   Set a configuration value
+  clear [key]       Clear a specific key or all configuration
+
+Configurable keys:
+  api-key    Your Shift API key
+  api-url    Backend API URL       (default: http://localhost:9000)
+  orch-url   Orchestrator URL      (default: http://localhost:9999)
+  ws-url     WebSocket URL         (default: ws://localhost:9999)
+
+URLs can also be set via environment variables:
+  SHIFT_API_URL, SHIFT_ORCH_URL, SHIFT_WS_URL
+
+Examples:
+  shift-cli config                                    Show config
+  shift-cli config set api-key sk-abc123              Set API key
+  shift-cli config set api-url https://api.shift.ai   Set API URL
+  shift-cli config clear api-key                      Clear API key
+  shift-cli config clear                              Clear all config
+`);
 program.parse();

package/build/utils/api-client.js

@@ -48,19 +48,28 @@ export async function fetchProjects(apiKey) {
  * Matching extension's init-scan API call
  */
 export async function sendInitScan(apiKey, projectId, payload) {
-    const response = await fetch(`${API_BASE_URL_ORCH}/api/projects/${projectId}/init-scan`, {
-        method: 'POST',
-        headers: {
-            'Authorization': `Bearer ${apiKey}`,
-            'Content-Type': 'application/json',
-        },
-        body: JSON.stringify(payload),
-    });
-    if (!response.ok) {
-        const text = await response.text();
-        throw new Error(text || `HTTP ${response.status}`);
+    try {
+        // Ensure proper URL construction with leading slash
+        const path = `/api/projects/${projectId}/init-scan`;
+        const url = new URL(path, API_BASE_URL_ORCH).toString();
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(payload),
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(text || `HTTP ${response.status}`);
+        }
+        return await response.json();
+    }
+    catch (error) {
+        // Re-throw for caller to handle; keep stack/context
+        throw error;
     }
-    return await response.json();
 }
 /**
  * Send update-drg request to backend

package/build/utils/config.js

@@ -132,6 +132,22 @@ export function ensureLocalShiftDir(projectRoot) {
         fs.mkdirSync(dir, { recursive: true });
     }
 }
+const SCAN_TARGET_TEMPLATE = [
+    {
+        language: null,
+        path: '',
+    },
+];
+/**
+ * Create .shift/scan_target.json with a template if it doesn't exist.
+ * Users can edit this file to manually specify scan targets.
+ */
+export function ensureScanTargetFile(projectRoot) {
+    const filePath = path.join(getLocalShiftDir(projectRoot), 'scan_target.json');
+    if (!fs.existsSync(filePath)) {
+        fs.writeFileSync(filePath, JSON.stringify(SCAN_TARGET_TEMPLATE, null, 2));
+    }
+}
 export function readProjectConfig(projectRoot) {
     try {
         const filePath = path.join(getLocalShiftDir(projectRoot), LOCAL_CONFIG_FILE);
@@ -152,8 +168,10 @@ export function writeProjectConfig(config, projectRoot) {
     // Also create .gitignore in .shift folder (matching extension)
     const gitignorePath = path.join(getLocalShiftDir(projectRoot), '.gitignore');
     if (!fs.existsSync(gitignorePath)) {
-        fs.writeFileSync(gitignorePath, '*\n!.gitignore\n!config.json\n');
+        fs.writeFileSync(gitignorePath, '*\n!.gitignore\n!config.json\n!scan_target.json\n');
     }
+    // Create scan_target.json template if it doesn't exist
+    ensureScanTargetFile(projectRoot);
 }
 export function getProjectId(projectRoot) {
     const config = readProjectConfig(projectRoot);

package/build/utils/shiftignore.js

@@ -0,0 +1,108 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import ignore from 'ignore';
+const SHIFTIGNORE_FILE = '.shiftignore';
+/**
+ * Load and parse a .shiftignore file from the project root.
+ * Returns an `ignore` instance that can test paths, or null if no .shiftignore exists.
+ *
+ * .shiftignore uses the same syntax as .gitignore:
+ *   - Blank lines are ignored
+ *   - Lines starting with # are comments
+ *   - Standard glob patterns (*, **, ?)
+ *   - Trailing / matches directories only
+ *   - Leading / anchors to root
+ *   - ! negates a pattern
+ */
+const DEFAULT_SHIFTIGNORE = `# .shiftignore — files and directories to exclude from Shift indexing
+# Uses the same syntax as .gitignore
+
+# Dependencies
+node_modules/
+vendor/
+bower_components/
+
+# Build output
+dist/
+build/
+out/
+.next/
+
+# Test & coverage
+coverage/
+.nyc_output/
+
+# Environment & secrets
+.env
+.env.*
+*.pem
+*.key
+
+# Logs
+*.log
+logs/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Python
+__pycache__/
+*.pyc
+venv/
+.venv/
+
+# Misc
+*.min.js
+*.min.css
+*.map
+`;
+/**
+ * Create a default .shiftignore file in the project root if one doesn't exist.
+ * Returns true if a new file was created, false if it already exists.
+ */
+export function scaffoldShiftIgnore(projectRoot) {
+    const ignorePath = path.join(projectRoot, SHIFTIGNORE_FILE);
+    if (fs.existsSync(ignorePath)) {
+        return false;
+    }
+    try {
+        fs.writeFileSync(ignorePath, DEFAULT_SHIFTIGNORE, 'utf-8');
+        return true;
+    }
+    catch (err) {
+        console.warn(`[ShiftIgnore] Warning: Could not create ${SHIFTIGNORE_FILE}: ${err.message}`);
+        return false;
+    }
+}
+export function loadShiftIgnore(projectRoot) {
+    const ignorePath = path.join(projectRoot, SHIFTIGNORE_FILE);
+    if (!fs.existsSync(ignorePath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(ignorePath, 'utf-8');
+        const ig = ignore();
+        ig.add(content);
+        return ig;
+    }
+    catch (err) {
+        console.warn(`[ShiftIgnore] Warning: Could not read ${SHIFTIGNORE_FILE}: ${err.message}`);
+        return null;
+    }
+}
+/**
+ * Filter an array of file paths through the shiftIgnore rules.
+ * Returns only paths that are NOT ignored.
+ */
+export function filterPaths(ig, paths) {
+    if (!ig)
+        return paths;
+    return paths.filter(p => !ig.ignores(p.replace(/\\/g, '/')));
+}

package/build/utils/tree-scanner.js

@@ -34,7 +34,7 @@ export function getProjectTree(workspaceRoot, options = {}) {
         try {
             const entries = fs.readdirSync(dirPath, { withFileTypes: true });
             for (const entry of entries) {
-                // Check if should be excluded
+                // Check if should be excluded by built-in patterns
                 if (exclude_patterns.some(pattern => entry.name.includes(pattern))) {
                     continue;
                 }
@@ -114,6 +114,23 @@ export function extractAllFilePaths(tree, basePath = '') {
  * Categorize files by type
  * Matching extension's categorizeFiles function
  */
+/**
+ * Count total lines of code across all project files
+ */
+export function countProjectLOC(rootPath, filePaths) {
+    let totalLOC = 0;
+    for (const filePath of filePaths) {
+        try {
+            const fullPath = path.join(rootPath, filePath);
+            const content = fs.readFileSync(fullPath, 'utf-8');
+            totalLOC += content.split('\n').length;
+        }
+        catch {
+            // Skip binary/unreadable files
+        }
+    }
+    return totalLOC;
+}
 export function categorizeFiles(tree, basePath = '') {
     const categories = {
         source_files: [],

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@latentforce/shift",
-    "version": "1.0.9",
+    "version": "1.0.11",
     "description": "Shift CLI - AI-powered code intelligence with MCP support",
     "type": "module",
     "main": "./build/index.js",