@latentforce/shift 1.0.11 → 1.0.12

package/README.md

@@ -10,71 +10,45 @@ Shift indexes your codebase, builds a dependency relationship graph (DRG), and p
 npm install -g @latentforce/shift
 ```
 
-Requires Node.js >= 18.
+## Getting an API Key
 
-## Quick Start
+1. Go to **https://dev-shift-lite.latentforce.ai/auth**
+2. **Sign up** for an account
+3. **Sign in** to your dashboard
+4. Copy your **API key** from the dashboard
 
-### Guest mode (zero-config)
+From the dashboard you can also **create a project** and **select a migration template** — or you can do both directly from the CLI (see below).
 
-```bash
-cd /path/to/your/project
-shift-cli init --guest        # Auto-creates guest key + project, scans, and indexes
-```
+## Quick Start
 
-### With an API key
+All commands **must be run** from your project's root directory:
 
 ```bash
-# Create a new project and index it (prompts for template selection)
-shift-cli init --api-key YOUR_KEY --project-name "My App"
-
-# Fully non-interactive (CI/CD friendly)
-shift-cli init --api-key YOUR_KEY --project-name "My App" --template TEMPLATE_ID
+cd /path/to/your/project
 ```
 
-### Interactive (original behavior)
+### Option A: Interactive (recommended)
 
 ```bash
-shift-cli start    # Configure API key and project interactively
-shift-cli init     # Index project files
+shift-cli start    # Step 1: Configure API key and project, launch daemon
+shift-cli init     # Step 2: Scan and index project files
+shift-cli status   # Step 3: Verify everything is connected
 ```
 
-## MCP Integration
+When you run `shift-cli start` interactively, it will:
+1. **Ask for your API key** — paste the key from your dashboard (or choose guest mode)
+2. **Ask to create or select a project** — you can either:
+   - **Select an existing project** from your account (if you created one on the dashboard)
+   - **Create a new project** from the CLI — it will prompt for a name (defaults to your directory name) and let you select a migration template
 
-After initializing your project, use `shift-cli add` to configure Shift's MCP server in your AI coding tool:
+### Option B: Non-interactive (CI/CD friendly)
 
 ```bash
-shift-cli add <tool>
+shift-cli init --api-key YOUR_KEY --project-name "My App"
 ```
 
-### Supported tools
-
-| 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.
-
-### Claude Desktop (manual)
+If a project named "My App" already exists in your account, it will be reused. Otherwise a new one is created with the specified template.
 
-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-cli",
-      "args": ["mcp"],
-      "env": {
-        "SHIFT_PROJECT_ID": "YOUR_PROJECT_ID"
-      }
-    }
-  }
-}
-```
 
 ## CLI Commands
 
@@ -82,12 +56,39 @@ Add to your config file (`%APPDATA%\Claude\claude_desktop_config.json` on Window
 |---------|-------------|
 | `shift-cli start` | Start the daemon and configure the project |
 | `shift-cli init` | Scan and index project files |
+| `shift-cli status` | Show current status |
 | `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 add <tool>` | Add Shift MCP server to an AI coding tool |
 | `shift-cli config` | Manage configuration |
 
+### `shift-cli start`
+
+Resolves authentication, configures the project, and launches a background daemon that maintains a WebSocket connection to the Shift backend.
+
+**When run interactively (no flags):**
+1. Prompts you to enter your API key or choose guest mode
+2. Prompts you to **select an existing project** or **create a new one**
+   - If creating: asks for a project name and lets you pick a migration template
+3. Saves config to `.shift/config.json`
+4. Launches the background daemon
+
+If you already created a project on the dashboard (https://dev-shift-lite.latentforce.ai), you can select it from the list. Otherwise, create one directly from the CLI.
+
+| Flag | Description |
+|------|-------------|
+| `--guest` | Use guest authentication (auto-creates a temporary project) |
+| `--api-key <key>` | Provide API key directly (skips the key prompt) |
+| `--project-name <name>` | Create new project or match existing by name (skips project prompt) |
+| `--project-id <id>` | Use existing project UUID (skips project prompt) |
+| `--template <id>` | Migration template ID for project creation |
+
+```bash
+shift-cli start                                     # Interactive setup (prompts for key + project)
+shift-cli start --guest                              # Quick start without API key
+shift-cli start --api-key <key> --project-name "My App"  # Non-interactive
+```
+
 ### `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.
@@ -106,30 +107,28 @@ If the project is already indexed, you will be prompted to re-index. Use `--forc
 ```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`
+### `shift-cli status`
 
-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 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 |
+Displays comprehensive information about the current Shift setup — API key status, project details, backend indexing state, and daemon health.
 
 ```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 status
 ```
 
 ### `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.
+Scans source files across all supported languages, detects git changes, and sends file contents to the backend for dependency analysis.
+
+**Supported languages and extensions:**
+
+| Language | Extensions |
+|----------|------------|
+| JavaScript / TypeScript | `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs` |
+| Python | `.py` |
+| C# | `.cs` |
+| C/C++ | `.cpp`, `.cc`, `.cxx`, `.h`, `.hpp`, `.c` |
 
 | Flag | Description |
 |------|-------------|
@@ -137,23 +136,19 @@ Scans JavaScript/TypeScript files (`.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`)
 
 **Modes:**
 - **incremental** (default) — sends only git-changed files for faster updates
-- **baseline** — sends all JS/TS files for a full re-analysis
+- **baseline** — sends all source 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>`
+### `shift-cli stop`
 
-Configures Shift's MCP server in the specified AI coding tool. Reads `project_id` from `.shift/config.json` (run `shift-cli init` first).
+Stops the background daemon process.
 
 ```bash
-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
+shift-cli stop
 ```
 
 ### `shift-cli config`
@@ -166,92 +161,141 @@ Manage Shift configuration (URLs, API key).
 | `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`.
+**Configurable key:** `api-key`
 
 ```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
 ```
+## MCP Integration
 
-## `.shiftignore`
+After initializing your project, use `shift-cli add` to configure Shift's MCP server in your AI coding tool:
 
-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`.
+```bash
+shift-cli add <tool>
+```
 
-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.
+### Supported tools
 
-### Syntax
+| 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` |
 
-- 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)
+For CLI-based tools, if the CLI is not installed, the command will print manual setup instructions.
 
-### Default `.shiftignore`
+### Claude Desktop (manual)
 
-The auto-generated file excludes common non-source directories and files:
+Add to your config file (`%APPDATA%\Claude\claude_desktop_config.json` on Windows, `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
 
-```gitignore
-# Dependencies
-node_modules/
-vendor/
-bower_components/
+```json
+{
+  "mcpServers": {
+    "shift": {
+      "command": "shift-cli",
+      "args": ["mcp"],
+      "env": {
+        "SHIFT_PROJECT_ID": "YOUR_PROJECT_ID"
+      }
+    }
+  }
+}
+```
+## `.shift/scan_target.json`
+
+Shift uses a `scan_target.json` file inside the `.shift/` directory to let you specify which parts of your codebase to scan and in which language. This is especially useful for monorepos or projects with multiple languages.
 
-# Build output
-dist/
-build/
-out/
-.next/
+A default template is **automatically created** the first time you run `shift-cli init` or `shift-cli start`. By default, it is unconfigured and the server will auto-detect scan targets. Edit the file to manually specify targets.
 
-# Test & coverage
-coverage/
-.nyc_output/
+### Valid Languages
 
-# Environment & secrets
-.env
-.env.*
-*.pem
-*.key
+```
+javascript, typescript, python, cpp, csharp
+```
 
-# Logs
-*.log
-logs/
+### Format
 
-# OS files
-.DS_Store
-Thumbs.db
+The file is a JSON array of objects, each with:
 
-# IDE
-.vscode/
-.idea/
-*.swp
-*.swo
+| Field | Type | Description |
+|-------|------|-------------|
+| `language` | `string \| null` | One of the valid languages above, or `null` for auto-detect |
+| `path` | `string` | Relative path from project root (empty string `""` for root) |
 
-# Python
-__pycache__/
-*.pyc
-venv/
-.venv/
+### Default Template (auto-generated)
 
-# Misc
-*.min.js
-*.min.css
-*.map
+```json
+[
+  {
+    "language": null,
+    "path": ""
+  }
+]
 ```
 
-### Bypassing `.shiftignore`
+When left as-is (single entry with `language: null` and `path: ""`), the server auto-detects scan targets.
 
-Use the `--no-ignore` flag to skip `.shiftignore` rules for a single run:
+### Examples
 
-```bash
-shift-cli init --no-ignore         # Index all files
-shift-cli update-drg --no-ignore   # Include ignored files in DRG update
+**Single-language project (TypeScript at root):**
+
+```json
+[
+  {
+    "language": "typescript",
+    "path": ""
+  }
+]
+```
+
+**Monorepo with multiple languages:**
+
+```json
+[
+  {
+    "language": "typescript",
+    "path": "frontend"
+  },
+  {
+    "language": "python",
+    "path": "backend"
+  },
+  {
+    "language": "csharp",
+    "path": "services/auth"
+  }
+]
+```
+
+**C++ project in a subdirectory:**
+
+```json
+[
+  {
+    "language": "cpp",
+    "path": "engine/src"
+  }
+]
+```
+
+**Mixed JavaScript and Python at root:**
+
+```json
+[
+  {
+    "language": "javascript",
+    "path": ""
+  },
+  {
+    "language": "python",
+    "path": ""
+  }
+]
 ```
 
 ## MCP Tools
@@ -270,4 +314,4 @@ Each tool accepts an optional `project_id` parameter. If not provided, it falls
 |------|----------|-------------|
 | 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) |
+| Scan targets | `.shift/scan_target.json` | Language and path targets for scanning (auto-created) |

package/package.json

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