@emend-ai/utim 1.46.27 → 1.46.30

package/README.md

@@ -1,82 +1,161 @@
-# UTIM CLI Agent: Enterprise Coder Assistant
-
-UTIM is an agentic developer CLI assistant designed to automate coding tasks directly inside your local terminal, featuring robust safety controls, self-healing quality gates, and local-first semantic memory.
-
----
-
-## 🚀 Quick Start
-
-### 1. Installation
-Install the package from your local source directory:
-
-```bash
-# Basic installation
-pip install .
-
-# Recommended: Full installation (includes semantic vector RAG & web search)
-pip install ".[full]"
-```
-
-### 2. Provider & Model Configuration
-Start the chat session:
-```bash
-utim
-```
-On first run, UTIM checks for `.utim/config.json`. If it does not exist, it runs a provider and model configuration wizard. You can configure:
-- **Default Providers**: OpenRouter, OpenAI, custom servers, etc.
-- **Model Picker**: Press `Ctrl+M` in the chat terminal at any time to configure, pick, add, or delete LLMs.
-
----
-
-## ⚡ Main CLI Commands
-
-- **`utim`**: Starts the interactive chat terminal (TUI).
-- **`utim task "<prompt>"`**: Executes a single task autonomously from the command line and exits. In an interactive terminal (`stdin` is a TTY) file writes and commands prompt for confirmation; when piped/scripted they run in auto-accept mode.
-- **`utim --dry-run`**: Starts the session in **Dry-Run Mode** (all code modifications and shell commands are simulated, not written/executed).
-- **`utim --sandbox`**: Runs all mutating shell command proposals in the intelligent local sandbox (untrusted commands will block until approved).
-- **`utim doctor`** / **`utim init`** / **`utim reset`**: Administrative commands for state diagnosis, initialization, and factory resets.
-
----
-
-## 🛠️ In-Chat Slash Commands
-
-Inside the interactive chat terminal, type these slash commands for direct workspace control:
-
-- **`/undo`**: Reverts the last assistant action, restoring files to their exact "before" state and rolling back messages.
-- **`/redo`**: Re-applies the last undone turn, re-writing files and restoring conversation logs.
-- **`/rewind <turn_index>`**: Rolls back the entire session to a specific conversation turn.
-- **`/doctor`**: Run diagnostics on environment variables, Python version, dependencies, API model connections, and MCP server status.
-- **`/report`**: Generates a support bundle under `.utim_tmp/report_bundle.zip` (automatically redacts secrets, passwords, or personal names/files).
-- **`/reset`**: Wipes the current chat history without deleting persistent local vector memory.
-
----
-
-## 🧠 Architecture & How it Works
-
-1. **Local Memory (`.utim/memory.json` & ChromaDB)**: 
-   - Global user preferences, rules, and facts are synced to a semantic vector database (`.utim_tmp/vector_db`).
-   - Relevant memories are dynamically fetched via semantic similarity (RAG) and injected into the system prompt context, preventing prompt bloating.
-2. **Undo/Redo Stack & Session State**:
-   - Every file change (writes, batch string edits, moves, deletions) computes a diff snapshot.
-   - The entire stack is serialized dynamically to `.utim/session_state.json`. You can close your shell, shut down your computer, and resume later with intact rollback features.
-3. **Workspace Boundary & Safety Controls**:
-   - Prior to writing files, UTIM performs **Pre-Commit Syntax Checks** (AST compilation for Python, JSON loads, JS/TS checks).
-   - If tests are available (`pytest`, `npm test`, etc.), UTIM runs them in a background **Regression testing loop**, prompting the model to self-heal code errors if assertions fail.
-   - **Interactive TUI mode** (`utim`): every file mutation shows an interactive diff dialog; the developer accepts, edits, or rejects individual hunks before they are applied.
-   - **CLI task mode** (`utim task`): when running in a real terminal, destructive operations (`rm`, package installs, `>` redirects) prompt for `y/n` confirmation. When stdin is piped/non-interactive all edits are auto-accepted.
-   - **Sandbox mode** (`utim --sandbox`): classifies every terminal command as safe or risky and blocks risky commands until explicitly approved.
-
----
-
-## ⚠️ What this Tool Can and Cannot Do
-
-### Can Do:
-- Read, write, and patch codebases safely.
-- Install and coordinate custom MCP (Model Context Protocol) servers.
-- Self-heal syntax and test errors before files are written.
-- Revert any file modification instantly.
-
-### Cannot Do:
-- **No Remote Code Execution**: Runs locally on your machine.
-- **Unverified Sensitive Reads Blocked**: Reading files or memory matching sensitive keys (like passwords, secret codes, or personal data) is blocked unless verified via your configured verification code.
-- **No Auto-Deletions**: Any command that deletes files outside the working directory is blocked automatically.
+# UTIM CLI Agent: Enterprise Coder Assistant
+
+UTIM is an agentic developer CLI assistant designed to automate coding tasks directly inside your local terminal, featuring robust safety controls, self-healing quality gates, and local-first semantic memory.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Installation
+Install the package from your local source directory:
+
+```bash
+# Basic installation
+pip install .
+
+# Recommended: Full installation (includes semantic vector RAG & web search)
+pip install ".[full]"
+```
+
+### 2. Provider & Model Configuration
+Start the chat session:
+```bash
+utim
+```
+On first run, UTIM checks for `.utim/config.json`. If it does not exist, it runs a provider and model configuration wizard. You can configure:
+- **Default Providers**: OpenRouter, OpenAI, custom servers, etc.
+- **Model Picker**: Press `Ctrl+M` in the chat terminal at any time to configure, pick, add, or delete LLMs.
+
+---
+
+## ⚡ Main CLI Commands
+
+- **`utim`**: Starts the interactive chat terminal (TUI).
+- **`utim task "<prompt>"`**: Executes a single task autonomously from the command line and exits. In an interactive terminal (`stdin` is a TTY) file writes and commands prompt for confirmation; when piped/scripted they run in auto-accept mode.
+- **`utim --dry-run`**: Starts the session in **Dry-Run Mode** (all code modifications and shell commands are simulated, not written/executed).
+- **`utim --sandbox`**: Runs all mutating shell command proposals in the intelligent local sandbox (untrusted commands will block until approved).
+- **`utim doctor`** / **`utim init`** / **`utim reset`**: Administrative commands for state diagnosis, initialization, and factory resets.
+
+---
+
+## 🛠️ In-Chat Slash Commands
+
+Inside the interactive chat terminal, type these slash commands for direct workspace control:
+
+- **`/undo`**: Reverts the last assistant action, restoring files to their exact "before" state and rolling back messages.
+- **`/redo`**: Re-applies the last undone turn, re-writing files and restoring conversation logs.
+- **`/rewind <turn_index>`**: Rolls back the entire session to a specific conversation turn.
+- **`/doctor`**: Run diagnostics on environment variables, Python version, dependencies, API model connections, and MCP server status.
+- **`/report`**: Generates a support bundle under `.utim_tmp/report_bundle.zip` (automatically redacts secrets, passwords, or personal names/files).
+- **`/reset`**: Wipes the current chat history without deleting persistent local vector memory.
+
+---
+
+## 🧠 Architecture & How it Works
+
+1. **Local Memory (`.utim/memory.json` & ChromaDB)**: 
+   - Global user preferences, rules, and facts are synced to a semantic vector database (`.utim_tmp/vector_db`).
+   - Relevant memories are dynamically fetched via semantic similarity (RAG) and injected into the system prompt context, preventing prompt bloating.
+2. **Undo/Redo Stack & Session State**:
+   - Every file change (writes, batch string edits, moves, deletions) computes a diff snapshot.
+   - The entire stack is serialized dynamically to `.utim/session_state.json`. You can close your shell, shut down your computer, and resume later with intact rollback features.
+3. **Workspace Boundary & Safety Controls**:
+   - Prior to writing files, UTIM performs **Pre-Commit Syntax Checks** (AST compilation for Python, JSON loads, JS/TS checks).
+   - If tests are available (`pytest`, `npm test`, etc.), UTIM runs them in a background **Regression testing loop**, prompting the model to self-heal code errors if assertions fail.
+   - **Interactive TUI mode** (`utim`): every file mutation shows an interactive diff dialog; the developer accepts, edits, or rejects individual hunks before they are applied.
+   - **CLI task mode** (`utim task`): when running in a real terminal, destructive operations (`rm`, package installs, `>` redirects) prompt for `y/n` confirmation. When stdin is piped/non-interactive all edits are auto-accepted.
+   - **Sandbox mode** (`utim --sandbox`): classifies every terminal command as safe or risky and blocks risky commands until explicitly approved.
+
+---
+
+## ⚠️ What this Tool Can and Cannot Do
+
+### Can Do:
+- Read, write, and patch codebases safely.
+- Install and coordinate custom MCP (Model Context Protocol) servers.
+- Self-heal syntax and test errors before files are written.
+- Revert any file modification instantly.
+
+### Cannot Do:
+- **No Remote Code Execution**: Runs locally on your machine.
+- **Unverified Sensitive Reads Blocked**: Reading files or memory matching sensitive keys (like passwords, secret codes, or personal data) is blocked unless verified via your configured verification code.
+- **No Auto-Deletions**: Any command that deletes files outside the working directory is blocked automatically.
+
+---
+
+## 📋 Compatibility Matrix
+
+| Component | Minimum Version | Recommended Version | Notes |
+|-----------|-----------------|---------------------|-------|
+| **Python** | 3.10 | 3.11+ | 3.10 required for asyncio features |
+| **pip** | 21.0 | 23.0+ | For modern dependency resolution |
+| **Node.js** | 18.0 | 20.0+ | Only if using MCP servers |
+| **Operating System** | | | |
+| - Windows | 10 (1903+) | 11 | PowerShell or CMD required |
+| - macOS | 11 (Big Sur) | 14 (Sonoma) | Terminal.app or iTerm2 |
+| - Linux | Ubuntu 20.04 | Ubuntu 22.04+ | Any modern distro with bash |
+| **Terminals** | | | |
+| - Windows Terminal | 1.0 | 1.19+ | Full color support |
+| - iTerm2 | 3.4+ | 3.5+ | Recommended on macOS |
+| - VS Code Terminal | 1.70+ | 1.85+ | Full support |
+| **Required Tools** | | | |
+| - git | 2.30 | 2.40+ | For undo/redo and diffs |
+| - Docker | 20.10 | 24.0+ | Optional, for sandbox mode |
+
+### Supported LLM Providers
+
+| Provider | API Type | Models Supported |
+|----------|----------|------------------|
+| OpenRouter | REST | Claude, GPT, Gemini, Mistral, etc. |
+| OpenAI | REST | GPT-4o, GPT-4 Turbo, GPT-3.5 |
+| Anthropic | REST | Claude 3.5, 3, 2 |
+| Google AI | REST | Gemini 1.5 Pro/Flash |
+| Azure OpenAI | REST | GPT-4, GPT-3.5 |
+| Ollama | Local | Llama 3, Mistral, CodeLlama |
+| Custom Server | REST | Any OpenAI-compatible API |
+
+---
+
+## 📄 Related Documentation
+
+- [📖 Full Documentation](https://utim.dev/docs)
+- [🔒 Security Policy](SECURITY.md) — vulnerability reporting, security@utim.dev
+- [🗄️ Data Handling Reference](DATA_HANDLING.md) — what stays local, what goes to backend, what goes to model providers
+- [📊 SLA & Support](SLA.md)
+- [🛡️ Privacy Policy](landing/src/docs_md/privacy.md)
+
+## 📦 Installation Methods
+
+### npm (recommended — works without Python pre-installed)
+```bash
+npm install -g @emend-ai/utim
+```
+
+### pip (from PyPI)
+```bash
+pip install utim-cli
+# Full install with optional features (web search, images, parsers)
+pip install "utim-cli[full]"
+```
+
+### Source install (development)
+```bash
+git clone https://github.com/emendai/utim.git
+cd utim
+pip install -e ".[full]"
+```
+
+### Smoke-test your install
+```bash
+utim --version     # Should print the current version
+utim doctor        # Runs diagnostics — all checks should pass
+```
+
+See [INSTALLATION_VERIFICATION.md](INSTALLATION_VERIFICATION.md) for detailed verification steps and troubleshooting.
+
+## 🔢 Version
+
+UTIM uses a single canonical version defined in [`utim_cli/_version.py`](utim_cli/_version.py).
+Run `python scripts/sync_version.py` to propagate a version bump to all surfaces
+(`package.json`, `pyproject.toml`, `CHANGELOG.md`) before releasing.
+

package/bin/utim.js

@@ -18,6 +18,17 @@ const isTermux =
     (process.env.PREFIX && process.env.PREFIX.includes('com.termux')) ||
     fs.existsSync('/data/data/com.termux');
 
+const path = require('path');
+let versionPin = '';
+try {
+    const pkg = require(path.join(__dirname, '..', 'package.json'));
+    if (pkg.version) {
+        versionPin = `==${pkg.version}`;
+    }
+} catch (_) {}
+
+const pipPackage = `utim-cli${versionPin}`;
+
 // ── Spinner (no-op when not a TTY) ───────────────────────────────────────────
 function createSpinner(text) {
     const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
@@ -69,7 +80,18 @@ function isUtimInstalled(python) {
             shell: isWin,
             windowsHide: true,
         });
-        return r.status === 0 && (r.stdout || '').includes('Name:');
+        if (r.status !== 0) return false;
+        
+        // Enforce that installed version matches expectedVersion
+        if (versionPin) {
+            const expectedVersion = versionPin.replace('==', '').trim();
+            const stdoutStr = r.stdout || '';
+            const match = stdoutStr.match(/^Version:\s*([^\r\n]+)/m);
+            if (match && match[1].trim() !== expectedVersion) {
+                return false; // version mismatch, force update/reinstall
+            }
+        }
+        return (r.stdout || '').includes('Name:');
     } catch (_) {
         return false;
     }
@@ -80,7 +102,7 @@ function runPip(python, extraFlags) {
     try {
         if (isWin) {
             // On Windows: spawn in a new Command Prompt window and block until it is closed.
-            const cmdStr = `title UTIM Setup & echo ======================================== & echo Installing UTIM Python engine and dependencies... & echo ======================================== & "${python}" -m pip install --upgrade ${extraFlags.join(' ')} utim-cli & echo ======================================== & echo Installation complete. You can close this window. & pause`;
+            const cmdStr = `title UTIM Setup & echo ======================================== & echo Installing UTIM Python engine and dependencies... & echo ======================================== & "${python}" -m pip install ${extraFlags.join(' ')} ${pipPackage} & echo ======================================== & echo Installation complete. You can close this window. & pause`;
             spawnSync('cmd.exe', ['/c', 'start', '/wait', 'cmd.exe', '/c', cmdStr], {
                 stdio: 'ignore',
                 shell: true,
@@ -92,7 +114,7 @@ function runPip(python, extraFlags) {
             // On macOS: use osascript to run it in a new Terminal window.
             const lockFile = require('path').join(os.tmpdir(), `utim_install_${Date.now()}.lock`);
             fs.writeFileSync(lockFile, 'running');
-            const installCmd = `echo "Installing UTIM Python engine..."; "${python}" -m pip install --upgrade ${extraFlags.join(' ')} utim-cli; rm -f "${lockFile}"; exit`;
+            const installCmd = `echo "Installing UTIM Python engine..."; "${python}" -m pip install ${extraFlags.join(' ')} ${pipPackage}; rm -f "${lockFile}"; exit`;
             const osaScript = `tell application "Terminal" to do script "${installCmd.replace(/"/g, '\\"')}"`;
             
             spawnSync('osascript', ['-e', osaScript], { stdio: 'ignore' });
@@ -113,10 +135,8 @@ function runPip(python, extraFlags) {
                 // versions of pydantic-core from PyPI and trying to compile from source.
                 // Instead, use --upgrade-strategy only-if-needed to keep the pre-compiled version.
                 pipArgs.push('--upgrade-strategy', 'only-if-needed');
-            } else {
-                pipArgs.push('--upgrade');
             }
-            pipArgs.push(...extraFlags, 'utim-cli');
+            pipArgs.push(...extraFlags, pipPackage);
 
             const r = spawnSync(python, pipArgs, {
                 stdio: 'inherit',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@emend-ai/utim",
-  "version": "1.46.27",
-  "description": "UTIM – Universal Terminal Intelligence Manager. An agentic AI coding assistant for your terminal.",
+  "version": "1.46.30",
+  "description": "UTIM \u2013 Universal Terminal Intelligence Manager. An agentic AI coding assistant for your terminal.",
   "keywords": [
     "ai",
     "agent",

package/scripts/postinstall.js

@@ -58,13 +58,25 @@ if (!python) {
     process.exit(0);
 }
 
+// Read the version from package.json to pin the python engine version
+const path = require('path');
+let versionPin = '';
+try {
+    const pkg = require(path.join(__dirname, '..', 'package.json'));
+    if (pkg.version) {
+        versionPin = `==${pkg.version}`;
+    }
+} catch (_) {}
+
+const pipPackage = `utim-cli${versionPin}`;
+
 // Silently pre-install in the background (pipe output, not inherit)
 // so the npm install output stays clean. Any failure is fine —
 // the launcher self-heals on first `utim` run.
 try {
     const r = spawnSync(
         python,
-        ['-m', 'pip', 'install', '--upgrade', '--quiet', 'utim-cli'],
+        ['-m', 'pip', 'install', '--quiet', pipPackage],
         {
             stdio: 'pipe',
             shell: isWin,