@latentforce/shift 1.0.9 → 1.0.10

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,13 +38,15 @@ shift-cli start    # Configure API key and project interactively
 shift-cli init     # Index project files
 ```
 
+## MCP Integration
+
 ### Add to Claude Code
 
 ```bash
 claude mcp add-json shift '{"type":"stdio","command":"shift-cli","args":["mcp"],"env":{"SHIFT_PROJECT_ID":"YOUR_PROJECT_ID"}}'
 ```
 
-Or using npx:
+Or using npx (no global install needed):
 
 ```bash
 claude mcp add-json shift '{"type":"stdio","command":"npx","args":["@latentforce/shift","mcp"],"env":{"SHIFT_PROJECT_ID":"YOUR_PROJECT_ID"}}'
@@ -68,52 +74,170 @@ 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 stop` | Stop the daemon |
 | `shift-cli status` | Show current status |
 | `shift-cli config` | Manage configuration |
 
-### CLI Flags
+### `shift-cli init`
 
-#### `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 and creates a default `.shiftignore` if one doesn't exist.
+
+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 |
+| `--no-ignore` | Skip `.shiftignore` rules for this run (send all files) |
 
-#### `shift-cli start`
+```bash
+shift-cli init                     # Interactive initialization
+shift-cli init --force             # Force re-index without prompt
+shift-cli init --no-ignore         # Index all files, skip .shiftignore
+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. Creates a default `.shiftignore` if one doesn't exist.
 
 | 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. Respects `.shiftignore` rules.
 
 | Flag | Description |
 |------|-------------|
 | `-m, --mode <mode>` | `baseline` (all files) or `incremental` (git-changed only, default) |
+| `--no-ignore` | Skip `.shiftignore` rules for this run (send all files) |
+
+**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 update-drg --no-ignore           # Include ignored files
+```
 
-### Update DRG
+### `shift-cli config`
 
-After initializing your project, update the dependency graph to keep code intelligence in sync:
+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 update-drg                    # Incremental (default) — only git-changed files
-shift-cli update-drg --mode baseline    # Full re-scan of all JS/TS files
+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
 ```
 
-Scans `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs` files.
+## `.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 +249,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/init.js

@@ -7,6 +7,7 @@ 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 { loadShiftIgnore, scaffoldShiftIgnore } from '../../utils/shiftignore.js';
 const require = createRequire(import.meta.url);
 const { version } = require('../../../package.json');
 const execAsync = promisify(exec);
@@ -120,6 +121,18 @@ export async function initCommand(options = {}) {
     }
     // Step 4: Scan project structure (matching extension's Step 6)
     console.log('[Init] Step 4/5: Scanning project structure...');
+    // Scaffold .shiftignore if it doesn't exist
+    if (scaffoldShiftIgnore(projectRoot)) {
+        console.log('[Init] ✓ Created default .shiftignore (edit it to customize ignored files)\n');
+    }
+    // Load .shiftignore (skip if --no-ignore)
+    const shiftIgnore = options.noIgnore ? null : loadShiftIgnore(projectRoot);
+    if (options.noIgnore) {
+        console.log('[Init] ⚠️  --no-ignore flag set — skipping .shiftignore rules\n');
+    }
+    else if (shiftIgnore) {
+        console.log('[Init] ✓ Applying .shiftignore rules\n');
+    }
     // Get project tree (matching extension's getProjectTree)
     const treeData = getProjectTree(projectRoot, {
         depth: 0, // Unlimited depth
@@ -136,6 +149,7 @@ export async function initCommand(options = {}) {
             'venv',
             'env',
         ],
+        shiftIgnore,
     });
     console.log(`[Init]   Files: ${treeData.file_count}`);
     console.log(`[Init]   Directories: ${treeData.dir_count}`);

package/build/cli/commands/start.js

@@ -1,6 +1,7 @@
 import { readProjectConfig, setProject } from '../../utils/config.js';
 import { startDaemon, getDaemonStatus } from '../../daemon/daemon-manager.js';
 import { resolveApiKey, resolveProject } from '../../utils/auth-resolver.js';
+import { scaffoldShiftIgnore } from '../../utils/shiftignore.js';
 export async function startCommand(options = {}) {
     const projectRoot = process.cwd();
     const isAuthInteractive = !options.guest && !options.apiKey;
@@ -37,6 +38,10 @@ export async function startCommand(options = {}) {
         console.error('❌ Failed to configure project');
         process.exit(1);
     }
+    // Scaffold .shiftignore if it doesn't exist
+    if (scaffoldShiftIgnore(projectRoot)) {
+        console.log('[Start] ✓ Created default .shiftignore (edit it to customize ignored files)\n');
+    }
     // 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

@@ -4,6 +4,7 @@ import { exec } from 'child_process';
 import { promisify } from 'util';
 import { getApiKey, readProjectConfig } from '../../utils/config.js';
 import { getProjectTree, extractAllFilePaths } from '../../utils/tree-scanner.js';
+import { loadShiftIgnore, filterPaths } from '../../utils/shiftignore.js';
 import { sendUpdateDrg } from '../../utils/api-client.js';
 const execAsync = promisify(exec);
 async function detectGitChanges(projectRoot, extensions) {
@@ -77,6 +78,13 @@ export async function updateDrgCommand(options = {}) {
     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...');
+    const shiftIgnore = options.noIgnore ? null : loadShiftIgnore(projectRoot);
+    if (options.noIgnore) {
+        console.log('[DRG] ⚠️  --no-ignore flag set — skipping .shiftignore rules\n');
+    }
+    else if (shiftIgnore) {
+        console.log('[DRG] ✓ Found .shiftignore — applying custom ignore rules\n');
+    }
     const treeData = getProjectTree(projectRoot, {
         depth: 0,
         exclude_patterns: [
@@ -92,6 +100,7 @@ export async function updateDrgCommand(options = {}) {
             'venv',
             'env',
         ],
+        shiftIgnore,
     });
     const allFiles = extractAllFilePaths(treeData.tree);
     const jstsFiles = allFiles.filter((filePath) => {
@@ -123,6 +132,10 @@ export async function updateDrgCommand(options = {}) {
     // 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);
+    // Filter git changes through .shiftignore
+    gitChanges.added = filterPaths(shiftIgnore, gitChanges.added);
+    gitChanges.modified = filterPaths(shiftIgnore, gitChanges.modified);
+    gitChanges.deleted = filterPaths(shiftIgnore, gitChanges.deleted);
     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]);

package/build/index.js

@@ -6,16 +6,25 @@ 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\n' +
+    '  Ignore rules:    .shiftignore (auto-created on first run)')
     .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 +32,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 +51,28 @@ 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. Creates a default .shiftignore if one doesn't exist.
+
+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')
+    .option('--no-ignore', 'Skip .shiftignore rules for this run (send all files)')
     .action(async (options) => {
     const { initCommand } = await import('./cli/commands/init.js');
     await initCommand({
@@ -60,35 +82,108 @@ program
         projectName: options.projectName,
         projectId: options.projectId,
         template: options.template,
+        noIgnore: options.noIgnore,
     });
 });
-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.
+  Creates a default .shiftignore if one doesn't exist.
+
+  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 --no-ignore         Index all files, ignore .shiftignore
+  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')
+    .option('--no-ignore', 'Skip .shiftignore rules for this run (send all files)')
     .action(async (options) => {
     const { updateDrgCommand } = await import('./cli/commands/update-drg.js');
-    await updateDrgCommand({ mode: options.mode });
+    await updateDrgCommand({ mode: options.mode, noIgnore: options.noIgnore });
 });
-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. Respects .shiftignore rules.
+
+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
+  shift-cli update-drg --no-ignore           Include ignored files
+`);
+// --- 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/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

@@ -21,7 +21,7 @@ const DEFAULT_EXCLUDE_PATTERNS = [
  * Get project tree - matching extension's getProjectTree function
  */
 export function getProjectTree(workspaceRoot, options = {}) {
-    const { depth = 0, exclude_patterns = DEFAULT_EXCLUDE_PATTERNS, } = options;
+    const { depth = 0, exclude_patterns = DEFAULT_EXCLUDE_PATTERNS, shiftIgnore = null, } = options;
     let file_count = 0;
     let dir_count = 0;
     let total_size = 0;
@@ -34,12 +34,21 @@ 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;
                 }
                 const itemPath = path.join(dirPath, entry.name);
                 const itemRelativePath = relativePath ? path.join(relativePath, entry.name) : entry.name;
+                // Check if should be excluded by .shiftignore
+                if (shiftIgnore) {
+                    // Use forward slashes for ignore matching; add trailing / for directories
+                    const testPath = itemRelativePath.replace(/\\/g, '/');
+                    const isDir = entry.isDirectory();
+                    if (shiftIgnore.ignores(isDir ? testPath + '/' : testPath)) {
+                        continue;
+                    }
+                }
                 if (entry.isDirectory()) {
                     dir_count++;
                     const children = scanDirectory(itemPath, currentDepth + 1, itemRelativePath);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@latentforce/shift",
-    "version": "1.0.9",
+    "version": "1.0.10",
     "description": "Shift CLI - AI-powered code intelligence with MCP support",
     "type": "module",
     "main": "./build/index.js",
@@ -38,6 +38,7 @@
     "dependencies": {
         "@modelcontextprotocol/sdk": "^1.25.3",
         "commander": "^12.0.0",
+        "ignore": "^7.0.5",
         "ws": "^8.14.0",
         "zod": "^3.25.76"
     },