@emend-ai/utim 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UTIM Dev Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# 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.

package/bin/utim.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+const { spawnSync, spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const args = process.argv.slice(2);
+
+// ── Find a working Python 3 interpreter ──────────────────────────────────────
+function findPython() {
+    for (const candidate of ['python3', 'python']) {
+        try {
+            const r = spawnSync(candidate, ['--version'], { encoding: 'utf8', timeout: 3000, shell: true });
+            const out = (r.stdout || '') + (r.stderr || '');
+            if (out.includes('Python 3')) return candidate;
+        } catch (_) {}
+    }
+    return null;
+}
+
+// ── Attempt to launch a command, return true if successful ───────────────────
+function tryLaunch(cmd, launchArgs) {
+    try {
+        const probe = spawnSync(cmd, ['--version'], { shell: true, timeout: 3000, encoding: 'utf8' });
+        const out = (probe.stdout || '') + (probe.stderr || '');
+        // accept if exit 0 OR if it printed something (some tools exit non-0 for --version)
+        if (probe.status === 0 || out.length > 0) {
+            const proc = spawn(cmd, launchArgs, { stdio: 'inherit', shell: true });
+            proc.on('exit', (code) => process.exit(code == null ? 0 : code));
+            return true;
+        }
+    } catch (_) {}
+    return false;
+}
+
+// ── Try the installed console_script entry point ──────────────────────────────
+function tryEntryPoint() {
+    return tryLaunch('utim-agent-core', args);
+}
+
+// ── Try via `python -m utim_cli.utim` ───────────────────────────────────────
+function tryModule(python) {
+    try {
+        const probe = spawnSync(python, ['-m', 'utim_cli', '--help'], { shell: true, timeout: 5000 });
+        if (probe.status === 0) {
+            const proc = spawn(python, ['-m', 'utim_cli.utim', ...args], { stdio: 'inherit', shell: true });
+            proc.on('exit', (code) => process.exit(code == null ? 0 : code));
+            return true;
+        }
+    } catch (_) {}
+    return false;
+}
+
+// ── Last resort: install from PyPI and retry ─────────────────────────────────
+function selfInstallAndRun(python) {
+    console.error('\n⚙  First run: installing UTIM Python engine from PyPI...');
+    const install = spawnSync(python, ['-m', 'pip', 'install', '--upgrade', 'utim-cli'], {
+        stdio: 'inherit',
+        shell: true,
+    });
+    if (install.status === 0) {
+        // Retry the entry point after install
+        return tryEntryPoint() || tryModule(python);
+    }
+    return false;
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+const python = findPython();
+
+const ok =
+    tryEntryPoint() ||
+    (python && tryModule(python)) ||
+    (python && selfInstallAndRun(python));
+
+if (!ok) {
+    console.error('\nError: UTIM Engine could not start.');
+    if (!python) {
+        console.error('Python 3 was not found. On Termux run:  pkg install python');
+    } else {
+        console.error(`Tried Python at: ${python}`);
+        console.error('Run manually:  pip install emendai-utim-agent  or  pip3 install --upgrade utim_cli');
+    }
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@emend-ai/utim",
+  "version": "1.0.0",
+  "description": "UTIM – Universal Terminal Intelligence Manager. An agentic AI coding assistant for your terminal.",
+  "keywords": [
+    "ai",
+    "agent",
+    "cli",
+    "coding-assistant",
+    "agentic",
+    "llm",
+    "mcp",
+    "utim"
+  ],
+  "homepage": "https://utim.ai",
+  "bugs": {
+    "url": "https://github.com/emendai/utim/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/emendai/utim.git"
+  },
+  "license": "MIT",
+  "author": "Emendai <support@emendai.com>",
+  "bin": {
+    "utim": "bin/utim.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "files": [
+    "bin/utim.js",
+    "scripts/postinstall.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,90 @@
+/**
+ * Cross-platform postinstall script for @emend-ai/utim.
+ *
+ * After `npm install -g @emend-ai/utim`, this script runs automatically to:
+ *   1. Locate a Python 3 interpreter on the user's machine.
+ *   2. Install the UTIM Python engine from PyPI:  pip install utim-cli
+ *   3. Set the execute bit on bin/utim.js (Unix / Termux only).
+ *
+ * The Python source code is NOT bundled inside this npm package.
+ * It is fetched from PyPI at install time.
+ */
+const { spawnSync } = require('child_process');
+const path = require('path');
+const os   = require('os');
+const fs   = require('fs');
+
+const pkgDir = path.resolve(__dirname, '..');
+
+// ── Find a usable Python 3 interpreter ────────────────────────────────────────
+function findPython() {
+    for (const candidate of ['python3', 'python']) {
+        try {
+            const r = spawnSync(candidate, ['--version'], {
+                encoding: 'utf8',
+                timeout: 4000,
+                shell: true,
+            });
+            const out = (r.stdout || '') + (r.stderr || '');
+            if (out.includes('Python 3')) return candidate;
+        } catch (_) {}
+    }
+    return null;
+}
+
+// ── Install UTIM Python engine from PyPI ──────────────────────────────────────
+function installFromPyPI(python) {
+    console.log('\n⚙  Installing UTIM Python engine from PyPI (pip install utim-cli)...\n');
+    try {
+        const r = spawnSync(
+            python,
+            ['-m', 'pip', 'install', '--upgrade', 'utim-cli'],
+            { stdio: 'inherit', shell: true }
+        );
+        return r.status === 0;
+    } catch (_) {
+        return false;
+    }
+}
+
+// ── Set execute bit on Unix / Termux ─────────────────────────────────────────
+function setExecuteBit() {
+    if (os.platform() !== 'win32') {
+        const binFile = path.join(pkgDir, 'bin', 'utim.js');
+        try {
+            fs.chmodSync(binFile, 0o755);
+        } catch (_) {
+            // non-fatal — npm usually sets the bit itself via package.json "bin"
+        }
+    }
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+const python = findPython();
+
+if (!python) {
+    console.error(
+        '\n⚠  Python 3 not found on this machine.\n' +
+        '   Please install Python 3.9+ from https://python.org and then run:\n' +
+        '     pip install utim-cli\n' +
+        '   to finish setting up UTIM.\n'
+    );
+    // Exit 0 so npm does not roll back the install — user can pip install manually
+    process.exit(0);
+}
+
+const ok = installFromPyPI(python);
+setExecuteBit();
+
+if (ok) {
+    console.log('\n✅  UTIM installed successfully. Run  utim  to get started.\n');
+} else {
+    console.warn(
+        '\n⚠  pip install failed. Try running manually:\n' +
+        '     pip install utim-cli\n' +
+        '   or:\n' +
+        '     pip3 install utim-cli\n'
+    );
+    // Exit 0 — don't break the npm install; user can manually pip install
+    process.exit(0);
+}