cowork-cli 0.2.8 → 1.0.0

package/README.md

@@ -54,7 +54,7 @@ cwk "Explain the data flow in the engine/ models"
 ## ✨ Features that Matter
 
 - **Zero-Whitespace UI**: High-density terminal output designed for professionals. No fluff, no headers, just data.
-- **Interactive Feedback**: The AI can now ask you clarifying questions via the `askUser` tool when it needs more context.
+- **Interactive Feedback**: The AI can request clarifications via the `askUser` tool or trigger an interactive `[ Yes ]  No` toggle using `askConfirm`.
 - **Smart Discovery**: Built-in `searchText`, `findFile`, and `projectTree` tools that respect your `.gitignore`.
 - **Surgical I/O**: Read entire files or specific line ranges (`readFileChunk`) with automatic binary detection.
 - **Piping Support**: Pipe logs or diffs directly into `cwk` for instant analysis.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-cli",
-  "version": "0.2.8",
+  "version": "1.0.0",
   "description": "work with cowork",
   "bin": {
     "cwk": "bin/cli.js"
@@ -35,4 +35,4 @@
     "ipaddr.js": "^2.4.0",
     "openai": "^6.38.0"
   }
-}
+}

package/src/configs/config.json

@@ -1,8 +1,11 @@
 {
   "accents": {
-    "orangex": "#D97757",
-    "greyx": "#808080",
-    "resetx": "#FFFFFF"
-  },
-  "systemPrompt": "You are a concise Developer Analyst. Use available tools proactively to investigate and process the user query. Provide a direct answer based on your findings. ENVIRONMENT: Terminal. STRICT RULES: 1. NO conversational filler or pleasantries. 2. NO Markdown formatting (do not use asterisks, backticks, or hashes). 3. NO XML or HTML tags. 4. Output ONLY structured, concise plain text. 5. Use simple spacing and indentation for structure. CWD: ${folder}. Year: ${year}."
+    "main":    "#7BA5DA",
+    "tool":    "#F2CF6E",
+    "data":    "#C2C6C5",
+    "success": "#7AC391",
+    "error":   "#E07070",
+    "dim":     "#606060",
+    "header":  "#A37ACC"
+  }
 }

package/src/configs/sys.txt

@@ -0,0 +1,33 @@
+# IDENTITY
+You are Cowork (cwk), an interactive CLI tool acting as a Full Engineering Read-Only Analyst.
+
+# CORE MANDATES
+- ONLY perform exactly what the user explicitly says.
+- NO unsolicited investigations, side tasks, or extra work of any kind.
+- Provide accurate data with absolute minimum token usage unless "deep work" is requested.
+
+# CONSTRAINTS (Terminal Environment)
+- NO conversational filler, pleasantries, preambles, or postambles.
+- NO Markdown (no *, `, #, or code blocks). NO XML/HTML tags.
+- Output ONLY structured, concise plain text with simple spacing/indentation.
+- Cite code locations using: file_path:line_number.
+
+# EXECUTION & STYLE
+- Answer directly without elaboration or explanation.
+- Use fewer than 4 lines (excluding tool use). One-word answers are preferred.
+- Use all tools efficiently (parallel/sequential) to minimize context usage.
+- Verify dependencies and mimic local code style; never assume availability.
+
+# EXAMPLES
+user: files in src/?
+assistant:
+src/foo.js
+src/bar.js
+
+user: where is foo?
+assistant:
+src/foo.js:12
+
+# CONTEXT
+Working directory: ${folder}
+Year: ${year}

package/src/engine/client.js

@@ -10,7 +10,7 @@ function clientLoader() {
   const config = loadConfig();
   
   if (!validateConfig(config)) {
-    throw new Error("Configuration missing or invalid. Please configure your ~/.env file (run 'btw --help' for details).");
+    throw new Error("Configuration missing or invalid. Please configure your ~/.env file (run 'cwk --help' for details).");
   }
 
   // Normalize baseURL: remove trailing slashes as the SDK appends paths starting with /

package/src/engine/models/BaseModel.js

@@ -1,6 +1,6 @@
 import { toolDefinitions, dispatchTool } from '../tools/index.js';
 import { logger } from '../../utils/logger.js';
-import { spinner } from '../../utils/ui.js';
+import { ui } from '../../utils/ui.js';
 import { outputFormatted } from '../../utils/outputFormatter.js';
 
 /**
@@ -46,9 +46,9 @@ export default class BaseModel {
       turn++;
       
       try {
-        spinner.start("Thinking");
+        ui.think();
         const response = await this._getCompletion();
-        spinner.stop();
+        ui.stop();
 
         const message = response.choices[0].message;
 
@@ -71,7 +71,7 @@ export default class BaseModel {
         await this._processToolCalls(message.tool_calls);
 
       } catch (err) {
-        spinner.stop();
+        ui.stop();
         // Deep error logging for API failures
         if (err.status) {
           logger.error(`[API Error] Status: ${err.status}`);
@@ -146,9 +146,9 @@ export default class BaseModel {
           const jitter = Math.random() * 500;
           const finalDelay = delay + jitter;
 
-          spinner.update(`Error ${err.status}. Retrying in ${(finalDelay/1000).toFixed(1)}s`);
+          ui.update(`Error ${err.status}. Retrying in ${(finalDelay/1000).toFixed(1)}s`);
           await new Promise(resolve => setTimeout(resolve, finalDelay));
-          spinner.update("Thinking");
+          ui.update('Thinking');
           continue;
         }
         throw err;
@@ -194,25 +194,21 @@ export default class BaseModel {
         else if (name === 'readFileChunk') displayArg = `${args.filePath} [L${args.startLine}-${args.endLine}]`;
         else displayArg = args.url || args.filePath || args.dirPath || args.path || args.pattern || JSON.stringify(args);
 
-        const displayStr = displayArg.length > 60 ? displayArg.slice(0, 57) + "..." : displayArg;
-
-        // NOTE: 'askUser' is interactive and handles its own semantic logging ([asking]) 
-        // to maintain terminal focus and avoid conflicts with the global spinner.
-        if (name !== 'askUser') {
-          logger.secondary(`[${label}] ${displayStr}`);
-          spinner.start(`[${label}] working`);
+        // ui.start() handles terminal-aware truncation internally.
+        if (name !== 'askUser' && name !== 'askConfirm') {
+          ui.start(label, displayArg);
         }
         
         const result = await dispatchTool(name, args);
         
-        if (name !== 'askUser') {
-          spinner.stop();
+        if (name !== 'askUser' && name !== 'askConfirm') {
+          ui.stop();
         }
 
         this.addMessage('tool', result, { tool_call_id: toolCall.id });
 
       } catch (err) {
-        spinner.stop();
+        ui.stop();
         const errorMsg = err.message;
         logger.error(`[FAILED] ${name}: ${errorMsg}`);
         

package/src/engine/run.js

@@ -6,7 +6,6 @@ import DefaultModel from './models/default.js';
 import GeminiModel from './models/gemini.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CONFIG_PATH = path.join(__dirname, '../configs/config.json');
 
 /**
  * Executes a chat completion query using the appropriate model handler.
@@ -21,17 +20,17 @@ export default async function runQuery(client, config, query) {
   }
 
   try {
-    // 1. Load and format system prompt from internal config
+    // 1. Load and format system prompt from internal sys.txt
     let systemPrompt = null;
     try {
-      const internalConfig = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
-      if (internalConfig.systemPrompt) {
-        systemPrompt = internalConfig.systemPrompt
+      const promptPath = path.join(__dirname, '../configs/sys.txt');
+      if (fs.existsSync(promptPath)) {
+        systemPrompt = fs.readFileSync(promptPath, 'utf8')
           .replace('${folder}', process.cwd())
-          .replace('${year}', new Date().getFullYear());
+          .replace(/\${year}/g, new Date().getFullYear());
       }
     } catch (e) {
-      // Fallback if config is missing - proceed without system prompt
+      // Fallback if prompt is missing - proceed without system prompt
     }
 
     const isGemini = config.model_type.toLowerCase() === 'gemini';

package/src/engine/tools/askConfirm.js

@@ -0,0 +1,34 @@
+import { ui } from '../../utils/ui.js';
+
+/**
+ * askConfirm tool — asks the user a yes/no question via the terminal.
+ *
+ * Accepted inputs (case-insensitive):
+ *   yes → y, yes
+ *   no  → n, no
+ *   cancel → Ctrl+C (treated as no, with dismissed flag)
+ *
+ * Any other input is silently erased and the prompt re-appears.
+ *
+ * @param {Object} args
+ * @param {string} args.question  The yes/no question to ask.
+ * @returns {Promise<string>}     JSON: { confirmed } or { confirmed, dismissed }
+ */
+export default async function askConfirm({ question }) {
+  // 1. Input validation
+  if (!question || typeof question !== 'string' || question.trim().length === 0) {
+    return JSON.stringify({ error: "'question' must be a non-empty string.", dismissed: true });
+  }
+
+  // 2. TTY guard — cannot prompt in pipes or CI environments
+  if (!process.stdin.isTTY) {
+    return JSON.stringify({
+      error: 'stdin is not a TTY. Cannot prompt in non-interactive environments.',
+      dismissed: true,
+    });
+  }
+
+  // 3. Delegate entirely to UIEngine — it owns all terminal state
+  const result = await ui.confirm(question);
+  return JSON.stringify(result);
+}

package/src/engine/tools/askUser.js

@@ -1,62 +1,32 @@
-import readlinePromises from 'readline/promises';
-import readline from 'readline';
-import { stdin as input, stdout as output } from 'process';
-import { formatSecondary } from '../../utils/logger.js';
+import { ui } from '../../utils/ui.js';
 
 /**
  * Implementation of the askUser tool.
- * Asks the user a single question via the terminal.
- * 
+ * Delegates rendering and input handling to the UIEngine singleton.
+ *
  * @param {Object} args
- * @param {string} args.question The question to ask the user.
- * @returns {Promise<string>} JSON string with answer or error.
+ * @param {string} args.question  The question to ask the user.
+ * @returns {Promise<string>}     JSON string: { answer } or { error, dismissed }.
  */
 export default async function askUser({ question }) {
-  // 1. Input Validation
-  if (!question) {
-    return "Error: 'question' parameter is required.";
-  }
-  
-  if (typeof question !== 'string' || question.trim().length === 0) {
-    return "Error: 'question' must be a non-empty string.";
+  // 1. Input validation
+  if (!question || typeof question !== 'string' || question.trim().length === 0) {
+    return JSON.stringify({ error: "'question' must be a non-empty string.", dismissed: true });
   }
 
-  // 2. TTY Check: Ensure we have a terminal to interact with
-  if (!input.isTTY) {
-    return "Error: stdin is not a TTY. Cannot prompt user in non-interactive environments.";
+  // 2. TTY check
+  if (!process.stdin.isTTY) {
+    return JSON.stringify({ error: 'stdin is not a TTY. Cannot prompt in non-interactive environments.', dismissed: true });
   }
 
-  const rl = readlinePromises.createInterface({ input, output });
-
-  return new Promise((resolve) => {
-    // 3. Graceful Signal Handling
-    rl.on('SIGINT', () => {
-      rl.close();
-      process.stdout.write(formatSecondary(` cancelled\n`));
-      resolve(JSON.stringify({ error: "user cancelled the request", dismissed: true }));
-    });
-
-    const doAsk = async () => {
-      try {
-        const answer = await rl.question(formatSecondary(`[asking] ${question} -> `));
-        const trimmed = answer.trim();
-
-        if (trimmed.length === 0) {
-          // Move cursor up and clear line reliably using Node's readline methods
-          readline.moveCursor(process.stdout, 0, -1);
-          readline.clearLine(process.stdout, 0);
-          readline.cursorTo(process.stdout, 0);
-          doAsk();
-        } else {
-          rl.close();
-          resolve(JSON.stringify({ answer: trimmed }));
-        }
-      } catch (err) {
-        rl.close();
-        resolve(JSON.stringify({ error: `System Error: ${err.message}`, dismissed: true }));
-      }
-    };
-
-    doAsk();
-  });
+  try {
+    const answer = await ui.ask(question);
+    return JSON.stringify({ answer });
+  } catch (err) {
+    // ui.ask() rejects with { cancelled: true } on SIGINT, or an Error otherwise.
+    if (err && err.cancelled) {
+      return JSON.stringify({ error: 'User cancelled the request.', dismissed: true });
+    }
+    return JSON.stringify({ error: `System Error: ${err.message}`, dismissed: true });
+  }
 }

package/src/engine/tools/index.js

@@ -8,6 +8,7 @@ import listTools from './listTools.js';
 import findFile from './findFile.js';
 import findDir from './findDir.js';
 import askUser from './askUser.js';
+import askConfirm from './askConfirm.js';
 
 export const toolDefinitions = [
   {
@@ -148,7 +149,7 @@ export const toolDefinitions = [
     type: "function",
     function: {
       name: "askUser",
-      description: "Ask the user a question via the terminal and get a text response.",
+      description: "Ask the user an open-ended question via the terminal and get a free-text response.",
       parameters: {
         type: "object",
         properties: {
@@ -157,6 +158,20 @@ export const toolDefinitions = [
         required: ["question"]
       }
     }
+  },
+  {
+    type: "function",
+    function: {
+      name: "askConfirm",
+      description: "Ask the user a yes/no confirmation question. Use this instead of askUser when only a boolean decision is needed. Returns { confirmed: true } for yes, { confirmed: false } for no, and { confirmed: false, dismissed: true } if the user cancels with Ctrl+C.",
+      parameters: {
+        type: "object",
+        properties: {
+          question: { type: "string", description: "The yes/no question to ask the user." }
+        },
+        required: ["question"]
+      }
+    }
   }
 ];
 
@@ -170,7 +185,8 @@ const toolImplementations = {
   listTools,
   findFile,
   findDir,
-  askUser
+  askUser,
+  askConfirm
 };
 
 /**

package/src/utils/configManager.js

@@ -17,10 +17,10 @@ export const loadConfig = () => {
       const envConfig = dotenv.parse(content);
       
       const config = {
-        model_name: envConfig.CWK_MODEL_NAME || envConfig.BTW_MODEL_NAME || envConfig.MODEL_NAME,
-        model_url: envConfig.CWK_MODEL_URL || envConfig.BTW_MODEL_URL || envConfig.MODEL_URL,
-        model_api_key: envConfig.CWK_MODEL_API_KEY || envConfig.BTW_MODEL_API_KEY || envConfig.MODEL_API_KEY,
-        model_type: envConfig.CWK_MODEL_TYPE || envConfig.BTW_MODEL_TYPE || envConfig.MODEL_TYPE
+        model_name: envConfig.CWK_MODEL_NAME || envConfig.MODEL_NAME,
+        model_url: envConfig.CWK_MODEL_URL || envConfig.MODEL_URL,
+        model_api_key: envConfig.CWK_MODEL_API_KEY || envConfig.MODEL_API_KEY,
+        model_type: envConfig.CWK_MODEL_TYPE || envConfig.MODEL_TYPE
       };
 
       // Remove undefined/empty values

package/src/utils/logger.js

@@ -9,12 +9,15 @@ let config;
 try {
   config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
 } catch (e) {
-  // Fallback config if file is missing or invalid
   config = {
     accents: {
-      orangex: "#D97757",
-      greyx: "#808080",
-      resetx: "#FFFFFF"
+      main:    '#7BA5DA',
+      tool:    '#F2CF6E',
+      data:    '#C2C6C5',
+      success: '#7AC391',
+      error:   '#E07070',
+      dim:     '#606060',
+      header:  '#A37ACC',
     }
   };
 }
@@ -26,20 +29,28 @@ function hexToAnsi(hex) {
   return `\x1b[38;2;${r};${g};${b}m`;
 }
 
+const reset = '\x1b[0m';
+
 const colors = {
-  main: hexToAnsi(config.accents.orangex),
-  secondary: hexToAnsi(config.accents.greyx),
-  normal: hexToAnsi(config.accents.resetx),
-  reset: '\x1b[0m'
+  main:    hexToAnsi(config.accents.main),
+  tool:    hexToAnsi(config.accents.tool),
+  data:    hexToAnsi(config.accents.data),
+  success: hexToAnsi(config.accents.success),
+  error:   hexToAnsi(config.accents.error),
+  dim:     hexToAnsi(config.accents.dim),
+  header:  hexToAnsi(config.accents.header),
 };
 
-export const formatMain = (text) => `${colors.main}${text}${colors.reset}`;
-export const formatSecondary = (text) => `${colors.secondary}${text}${colors.reset}`;
-export const formatNormal = (text) => `${colors.normal}${text}${colors.reset}`;
+export const formatMain      = (text) => `${colors.main}${text}${reset}`;
+export const formatSecondary = (text) => `${colors.tool}${text}${reset}`;
+export const formatNormal    = (text) => `${colors.data}${text}${reset}`;
+export const formatError     = (text) => `${colors.error}${text}${reset}`;
+export const formatDim       = (text) => `${colors.dim}${text}${reset}`;
+export const formatHeader    = (text) => `${colors.header}${text}${reset}`;
 
 export const logger = {
-  main: (msg) => console.log(formatMain(msg)),
+  main:      (msg) => console.log(formatMain(msg)),
   secondary: (msg) => console.log(formatSecondary(msg)),
-  normal: (msg) => console.log(formatNormal(msg)),
-  error: (msg) => console.error(formatMain(msg))
+  normal:    (msg) => console.log(formatNormal(msg)),
+  error:     (msg) => console.error(formatError(msg)),
 };

package/src/utils/ui.js

@@ -1,68 +1,582 @@
-import { formatSecondary } from './logger.js';
+import { createInterface } from 'node:readline';
+
+// ---------------------------------------------------------------------------
+// Design tokens
+// ---------------------------------------------------------------------------
+
+const COLORS = {
+  main:    [123, 165, 218],  // #7BA5DA – blue    (chrome, glyphs, parens)
+  tool:    [242, 207, 110],  // #F2CF6E – amber   (label / tool name)
+  data:    [194, 198, 197],  // #C2C6C5 – silver  (args, data)
+  success: [122, 195, 145],  // #7AC391 – green   (● on stop)
+  error:   [224, 112, 112],  // #E07070 – red     (● on fail)
+  dim:     [ 96,  96,  96],  // #606060 – grey    (dim annotations)
+  header:  [163, 122, 204],  // #A37ACC – purple  (● header dot)
+};
+
+const THOUGHTS = [
+  'Thinking...', 'Brewing...',      'Grooming...',     'Analyzing...',
+  'Investigating...', 'Processing...', 'Synthesizing...', 'Exploring...',
+  'Mapping...',  'Reasoning...',    'Meditating...',   'Computing...',
+  'Crawling...', 'Scanning...',
+];
+
+const GLYPHS = {
+  header:  '●',
+  dot:     '●',   // color-coded: green = stop, red = fail
+  ask:     '◇',
+  input:   '>',
+  spinner: ['⣾', '⣽', '⣻', '⢿', '⡿', '⣟', '⣯', '⣷'],
+};
+
+// ---------------------------------------------------------------------------
+// State constants
+// ---------------------------------------------------------------------------
+
+const STATE = Object.freeze({
+  IDLE:     'IDLE',
+  SPINNING: 'SPINNING',
+  THINKING: 'THINKING',
+  ASKING:   'ASKING',
+});
+
+// ---------------------------------------------------------------------------
+// UIEngine
+// ---------------------------------------------------------------------------
 
 /**
- * A minimalist terminal spinner that uses text-based dot animations.
+ * UIEngine – State-Based Reactive Terminal Interface.
+ *
+ * State machine:
+ *
+ *   IDLE ──start()──▶ SPINNING
+ *   IDLE ──think()──▶ THINKING
+ *   IDLE ──ask()───▶  ASKING
+ *   SPINNING/THINKING ──stop()──▶ IDLE   (● green)
+ *   SPINNING/THINKING ──fail()──▶ IDLE   (● red)
+ *   ASKING ──resolve/cancel──▶ IDLE
+ *
+ * Reactive renderer:
+ *   _vdom tracks { frame, label, data } currently on screen.
+ *   Each tick diffs next values against _vdom and calls only the
+ *   narrowest patch operation needed — no full-line clears on animation ticks.
+ *
+ *   Patch cost per tick (SPINNING, no update):
+ *     \r + 1 colored char  ≈ 22 bytes  (no clear)
+ *
+ * Public API:
+ *   ui.start(label, data?)   → SPINNING
+ *   ui.think()               → THINKING (rotating thought words)
+ *   ui.update(data)          – swap data field in-place
+ *   ui.stop(msg?)            → IDLE  (● green)
+ *   ui.fail(msg?)            → IDLE  (● red)
+ *   ui.ask(question)         → Promise<string>
+ *   ui.log(text)             – safe from any state
+ *   ui.header(title)         – safe from any state
+ *   ui.footer(secs)          – safe from any state
+ *   ui.cleanup()             – restore cursor, safe from any state
+ *   ui.state                 – read-only current state string
  */
-export class Spinner {
+export class UIEngine {
   constructor() {
-    this.frames = ['', '.', '..', '...'];
-    this.interval = null;
-    this.currentFrame = 0;
-    this.text = '';
-    this.isSpinning = false;
+    this._stream     = process.stdout;
+    this._state      = STATE.IDLE;
+    this._timer      = null;
+    this._frameIdx   = 0;
+    this._thoughtIdx = 0;
+
+    // What the spinner is currently representing
+    this._ctx = { label: '', data: '' };
+
+    // What is actually rendered on the terminal right now
+    // null = field not yet on screen / cleared
+    this._vdom = { frame: null, label: null, data: null };
+
+    // Re-render on resize — layout metrics change with terminal width
+    this._stream.on('resize', () => {
+      if (this._state === STATE.SPINNING || this._state === STATE.THINKING) {
+        this._paint(); // full repaint: truncation bounds changed
+      }
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Public state getter
+  // -------------------------------------------------------------------------
+
+  /** @returns {'IDLE'|'SPINNING'|'THINKING'|'ASKING'} */
+  get state() { return this._state; }
+
+  // -------------------------------------------------------------------------
+  // ANSI helpers (pure, no side-effects)
+  // -------------------------------------------------------------------------
+
+  _rgb([r, g, b], text) { return `\x1b[38;2;${r};${g};${b}m${text}\x1b[0m`; }
+  _bold(text)  { return `\x1b[1m${text}\x1b[0m`; }
+  _dim(text)   { return `\x1b[2m${text}\x1b[0m`; }
+
+  // -------------------------------------------------------------------------
+  // Terminal control
+  // -------------------------------------------------------------------------
+
+  _w(str)        { this._stream.write(str); }
+  _clearLine()   { this._w('\r\x1b[K'); }
+  _hideCursor()  { this._w('\x1b[?25l'); }
+  _showCursor()  { this._w('\x1b[?25h'); }
+  _moveUp(n = 1) { this._w(`\x1b[${n}A`); }
+  /** Move cursor to visible column n (0-indexed). */
+  _toCol(n)      { this._w(n > 0 ? `\r\x1b[${n}C` : '\r'); }
+
+  // -------------------------------------------------------------------------
+  // Layout helpers
+  // -------------------------------------------------------------------------
+
+  /**
+   * How many visible chars are available for the data field,
+   * given the current terminal width and label length.
+   *
+   * Line layout (visible columns):
+   *   frame(1) space(1) label(L) space(1) open(1) data(D) close(1)
+   *   total = 5 + L + D   →   D = width - 5 - L - margin(2)
+   */
+  _availWidth(label) {
+    const w = this._stream.columns || 80;
+    return Math.max(0, w - 7 - label.length);
+  }
+
+  /**
+   * Column where '(' starts  =  frame(1) + space(1) + label(L) + space(1)
+   *                          =  3 + L
+   */
+  _parenCol(label) { return 3 + label.length; }
+
+  // -------------------------------------------------------------------------
+  // Smart truncation
+  // -------------------------------------------------------------------------
+
+  /**
+   * Truncate to maxWidth visible chars.
+   * Paths: prefer …/parent/file → …/file → …tail.
+   * Other: tail-ellipsis.
+   */
+  _truncate(text, maxWidth) {
+    if (!text || text.length <= maxWidth) return text;
+    if (maxWidth <= 2) return '…';
+
+    if (text.includes('/')) {
+      const parts = text.split('/');
+      const file  = parts.pop();
+      const par   = parts.pop() || '';
+
+      const wp = `…/${par}/${file}`;
+      if (wp.length <= maxWidth) return wp;
+
+      const wf = `…/${file}`;
+      if (wf.length <= maxWidth) return wf;
+
+      return `…${file.slice(-(maxWidth - 1))}`;
+    }
+
+    return text.slice(0, maxWidth - 1) + '…';
   }
 
+  // -------------------------------------------------------------------------
+  // Patch operations — surgical cursor-positioned writes, no full-line clears
+  // -------------------------------------------------------------------------
+
   /**
-   * Starts the spinner with a base message.
+   * Overwrite only the spinner frame character at col 0.
+   * Cost: \r + ~22 bytes of ANSI + 1 char. Rest of line untouched.
    */
-  start(text) {
-    if (this.isSpinning) this.stop(true);
-    process.stdout.write('\x1b[?25l'); // Hide cursor
-    this.text = text;
-    this.isSpinning = true;
-    this.render();
-    this.interval = setInterval(() => {
-      this.currentFrame = (this.currentFrame + 1) % this.frames.length;
-      this.render();
-    }, 400); // Slower interval for dot cycle
+  _patchFrame(frame) {
+    this._w(`\r${this._rgb(COLORS.main, frame)}`);
+    // cursor lands at col 1 — the rest of the line is physically untouched
   }
 
   /**
-   * Updates the base text message.
+   * Overwrite label and everything to the right of it (col 2 onward).
+   * Used when label changes (THINKING rotation) or on initial paint for label region.
+   * Returns the truncated data string that was written.
    */
-  update(text) {
-    this.text = text;
-    if (this.isSpinning) this.render();
+  _patchFromLabel(label, data) {
+    const td = data ? this._truncate(data, this._availWidth(label)) : '';
+    const dataStr = td
+      ? ` ${this._rgb(COLORS.main, '(')}${this._rgb(COLORS.data, td)}${this._rgb(COLORS.main, ')')}`
+      : '';
+    // go to col 2, clear to EOL, write new label + optional data
+    this._w(`\r\x1b[2C\x1b[K${this._rgb(COLORS.tool, label)}${dataStr}`);
+    return td;
   }
 
   /**
-   * Stops the spinner and restores the cursor.
-   * @param {boolean} clear If true, clears the entire line.
+   * Overwrite only the data field (from the '(' position onward).
+   * Used when data changes via update() — label and frame untouched.
+   * Returns the truncated data string that was written.
    */
-  stop(clear = true) {
-    if (!this.isSpinning) {
-      process.stdout.write('\x1b[?25h'); // Ensure cursor is shown
-      return;
+  _patchFromData(label, data) {
+    const td = data ? this._truncate(data, this._availWidth(label)) : '';
+    const dataStr = td
+      ? `${this._rgb(COLORS.main, '(')}${this._rgb(COLORS.data, td)}${this._rgb(COLORS.main, ')')}`
+      : '';
+    // jump to paren col, clear to EOL, write new data section
+    this._toCol(this._parenCol(label));
+    this._w(`\x1b[K${dataStr}`);
+    return td;
+  }
+
+  // -------------------------------------------------------------------------
+  // Full repaint — only at state transitions or terminal resize
+  // -------------------------------------------------------------------------
+
+  _paint() {
+    const { label, data } = this._ctx;
+    const frame = GLYPHS.spinner[this._frameIdx];
+    const td = data ? this._truncate(data, this._availWidth(label)) : '';
+    const dataStr = td
+      ? ` ${this._rgb(COLORS.main, '(')}${this._rgb(COLORS.data, td)}${this._rgb(COLORS.main, ')')}`
+      : '';
+
+    this._clearLine(); // ← one of the very few places \r\x1b[K appears
+    this._w(`${this._rgb(COLORS.main, frame)} ${this._rgb(COLORS.tool, label)}${dataStr}`);
+
+    // Sync virtual DOM to match what's on screen
+    this._vdom = { frame, label, data: td };
+  }
+
+  // -------------------------------------------------------------------------
+  // Animation tick — diffed, minimal writes
+  // -------------------------------------------------------------------------
+
+  _tick() {
+    this._frameIdx = (this._frameIdx + 1) % GLYPHS.spinner.length;
+
+    const nextFrame = GLYPHS.spinner[this._frameIdx];
+    let   nextLabel = this._ctx.label;
+
+    // THINKING: rotate label every 8 ticks  (~800 ms at 100 ms interval)
+    if (this._state === STATE.THINKING && this._frameIdx % 8 === 0) {
+      this._thoughtIdx = (this._thoughtIdx + 1) % THOUGHTS.length;
+      nextLabel = THOUGHTS[this._thoughtIdx];
+      this._ctx.label = nextLabel;
     }
-    clearInterval(this.interval);
-    this.isSpinning = false;
-    if (clear) {
-      process.stdout.write('\r\x1b[K'); // Clear entire line
+
+    const labelChanged = nextLabel !== this._vdom.label;
+    const frameChanged = nextFrame !== this._vdom.frame;
+
+    if (labelChanged) {
+      // Repaint from col 2 onward (label + data)
+      const td = this._patchFromLabel(nextLabel, this._ctx.data);
+      this._vdom.label = nextLabel;
+      this._vdom.data  = td; // avail width may have changed with new label length
+    }
+
+    if (frameChanged) {
+      // Cheapest possible update: 1 char at col 0
+      this._patchFrame(nextFrame);
+      this._vdom.frame = nextFrame;
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Internal transition helpers
+  // -------------------------------------------------------------------------
+
+  /**
+   * Silently clear the active spinner line and stop the timer.
+   * No completion line printed. Used when start()/think() replaces
+   * an existing spinner, or on cleanup().
+   */
+  _abort() {
+    if (this._state === STATE.IDLE || this._state === STATE.ASKING) return;
+    clearInterval(this._timer);
+    this._timer = null;
+    this._clearLine();
+    this._vdom  = { frame: null, label: null, data: null };
+    this._state = STATE.IDLE;
+    this._showCursor();
+  }
+
+  /**
+   * Stop the spinner and commit a styled completion line.
+   * @param {string|undefined} msg   - override data shown in parens
+   * @param {number[]}         color - COLORS.success or COLORS.error
+   */
+  _commit(msg, color) {
+    if (this._state === STATE.IDLE || this._state === STATE.ASKING) return;
+    clearInterval(this._timer);
+    this._timer = null;
+    this._clearLine();
+
+    const label = this._state === STATE.THINKING ? 'Thought' : this._ctx.label;
+    const raw   = msg !== undefined ? msg : this._ctx.data;
+    const td    = raw ? this._truncate(raw, this._availWidth(label)) : '';
+    const dataStr = td
+      ? ` ${this._rgb(COLORS.main, '(')}${this._rgb(COLORS.data, td)}${this._rgb(COLORS.main, ')')}`
+      : '';
+
+    this._w(`${this._rgb(color, GLYPHS.dot)} ${this._rgb(COLORS.tool, label)}${dataStr}\n`);
+    this._vdom  = { frame: null, label: null, data: null };
+    this._state = STATE.IDLE;
+    this._showCursor();
+  }
+
+  // -------------------------------------------------------------------------
+  // Public API
+  // -------------------------------------------------------------------------
+
+  /**
+   * Enter SPINNING state with a fixed label.
+   * Silently replaces any active spinner.
+   */
+  start(label, data = '') {
+    this._abort();
+    this._ctx        = { label, data };
+    this._frameIdx   = 0;
+    this._state      = STATE.SPINNING;
+    this._hideCursor();
+    this._paint();
+    this._timer = setInterval(() => this._tick(), 100);
+  }
+
+  /**
+   * Enter THINKING state — label rotates through THOUGHTS words.
+   * Silently replaces any active spinner.
+   */
+  think() {
+    this._abort();
+    this._thoughtIdx = 0;
+    this._ctx        = { label: THOUGHTS[0], data: '' };
+    this._frameIdx   = 0;
+    this._state      = STATE.THINKING;
+    this._hideCursor();
+    this._paint();
+    this._timer = setInterval(() => this._tick(), 100);
+  }
+
+  /**
+   * Swap the data field of a running spinner without stopping it.
+   * Only writes to terminal if the (truncated) value actually changed.
+   */
+  update(data) {
+    if (this._state !== STATE.SPINNING && this._state !== STATE.THINKING) return;
+    const td = data ? this._truncate(data, this._availWidth(this._ctx.label)) : '';
+    if (td === this._vdom.data) return; // nothing visible changed
+    this._ctx.data  = data;
+    const written   = this._patchFromData(this._ctx.label, data);
+    this._vdom.data = written;
+  }
+
+  /**
+   * Finish the spinner with a green ● and an optional final message.
+   * SPINNING/THINKING → IDLE.
+   */
+  stop(msg) { this._commit(msg, COLORS.success); }
+
+  /**
+   * Finish the spinner with a red ● and an optional final message.
+   * SPINNING/THINKING → IDLE.
+   */
+  fail(msg) { this._commit(msg, COLORS.error); }
+
+  /**
+   * Print a line of text without disturbing the active spinner.
+   * Safe from any state.
+   * @param {string} text  Pre-formatted string (may contain ANSI codes).
+   */
+  log(text) {
+    if (this._state === STATE.SPINNING || this._state === STATE.THINKING) {
+      this._clearLine();
+      this._w(`${text}\n`);
+      this._paint(); // restore spinner below
     } else {
-      process.stdout.write('\n'); 
+      this._w(`${text}\n`);
     }
-    process.stdout.write('\x1b[?25h'); // Show cursor
-    this.currentFrame = 0;
   }
 
   /**
-   * @private
+   * Print a ● header line. Safe from any state via log().
+   */
+  header(title) {
+    this.log(
+      `${this._rgb(COLORS.header, GLYPHS.header)} ${this._rgb(COLORS.main, this._bold(title.toLowerCase()))}`
+    );
+  }
+
+  /**
+   * Prompt the user for input with a styled ◇ Question prompt.
+   * Auto-stops any active spinner first.
+   * Resolves with the trimmed answer; rejects { cancelled: true } on SIGINT.
+   * Re-prompts silently on empty input.
+   * @param {string} question
+   * @returns {Promise<string>}
+   */
+  ask(question) {
+    this._abort();
+
+    if (!process.stdin.isTTY) {
+      return Promise.reject(new Error('stdin is not a TTY'));
+    }
+
+    this._state = STATE.ASKING;
+
+    return new Promise((resolve, reject) => {
+      const rl = createInterface({ input: process.stdin, output: this._stream });
+
+      const w      = this._stream.columns || 80;
+      const avail  = Math.max(0, w - 14); // ◇ Ask ( ... )
+      const truncQ = this._truncate(question, avail);
+
+      this._w(
+        `${this._rgb(COLORS.main, GLYPHS.ask)} ` +
+        `${this._rgb(COLORS.tool, 'Ask')} ` +
+        `${this._rgb(COLORS.main, '(')}${this._rgb(COLORS.data, truncQ)}${this._rgb(COLORS.main, ')')}\n`
+      );
+
+      const prompt = `${this._rgb(COLORS.main, this._bold(GLYPHS.input))} `;
+
+      rl.on('SIGINT', () => {
+        rl.close();
+        this._showCursor();
+        this._state = STATE.IDLE;
+        reject({ cancelled: true });
+      });
+
+      const doAsk = () => {
+        rl.question(prompt, (raw) => {
+          const ans = raw.trim();
+          if (!ans) {
+            this._moveUp(1);
+            this._clearLine();
+            doAsk();
+            return;
+          }
+          rl.close();
+          this._moveUp(1);
+          this._clearLine();
+          this._w(`${this._rgb(COLORS.main, this._bold(GLYPHS.input))} ${ans}\n`);
+          this._state = STATE.IDLE;
+          resolve(ans);
+        });
+      };
+
+      doAsk();
+    });
+  }
+
+  /**
+   * Prompt the user for a yes/no confirmation with an interactive toggle.
+   *
+   * Behaviour:
+   *  • Renders a `[ Yes ]  No` toggle selector.
+   *  • Use Arrow Keys, Tab, or Space to toggle. Y/N to select directly.
+   *  • Enter to confirm.
+   *  • Ctrl+C (SIGINT) → resolves { confirmed: false, dismissed: true }.
+   *  • Answer is echoed in green (yes) or red (no).
+   *
+   * @param {string} question
+   * @returns {Promise<{ confirmed: boolean, dismissed?: true }>}
+   */
+  confirm(question) {
+    this._abort();
+
+    if (!process.stdin.isTTY) {
+      return Promise.resolve({ confirmed: false, dismissed: true });
+    }
+
+    this._state = STATE.ASKING;
+
+    return new Promise((resolve) => {
+      const w      = this._stream.columns || 80;
+      const avail  = Math.max(0, w - 14);
+      const truncQ = this._truncate(question, avail);
+
+      this._w(
+        `${this._rgb(COLORS.main, GLYPHS.ask)} ` +
+        `${this._rgb(COLORS.tool, 'Ask')} ` +
+        `${this._rgb(COLORS.main, '(')}${this._rgb(COLORS.data, truncQ)}${this._rgb(COLORS.main, ')')}\n`
+      );
+
+      let selectedYes = true;
+
+      const renderToggle = () => {
+        this._clearLine();
+        const yesLabel = selectedYes ? this._rgb(COLORS.main, this._bold('[ Yes ]')) : this._dim('  Yes  ');
+        const noLabel  = !selectedYes ? this._rgb(COLORS.main, this._bold('[ No ]')) : this._dim('  No  ');
+        this._w(`${this._rgb(COLORS.main, this._bold(GLYPHS.input))}  ${yesLabel}  ${noLabel}`);
+      };
+
+      this._hideCursor();
+      renderToggle();
+
+      const onData = (data) => {
+        const str = data.toString();
+        
+        // Ctrl+C
+        if (str === '\u0003') {
+          cleanup();
+          this._clearLine();
+          this._w(`${this._rgb(COLORS.main, this._bold(GLYPHS.input))} ${this._dim('cancelled')}\n`);
+          this._showCursor();
+          this._state = STATE.IDLE;
+          resolve({ confirmed: false, dismissed: true });
+          return;
+        }
+
+        // Enter
+        if (str === '\r' || str === '\n') {
+          cleanup();
+          this._clearLine();
+          const finalColor = selectedYes ? COLORS.success : COLORS.error;
+          const finalStr   = selectedYes ? 'yes' : 'no';
+          this._w(`${this._rgb(COLORS.main, this._bold(GLYPHS.input))} ${this._rgb(finalColor, finalStr)}\n`);
+          this._showCursor();
+          this._state = STATE.IDLE;
+          resolve({ confirmed: selectedYes });
+          return;
+        }
+
+        // Toggle keys (Left, Right, Up, Down, Tab, Space)
+        if (str === '\u001b[D' || str === '\u001b[C' || str === '\u001b[A' || str === '\u001b[B' || str === '\t' || str === ' ') {
+          selectedYes = !selectedYes;
+          renderToggle();
+        } else if (str.toLowerCase() === 'y') {
+          selectedYes = true;
+          renderToggle();
+        } else if (str.toLowerCase() === 'n') {
+          selectedYes = false;
+          renderToggle();
+        }
+      };
+
+      const cleanup = () => {
+        if (process.stdin.isTTY) {
+          process.stdin.setRawMode(false);
+        }
+        process.stdin.off('data', onData);
+        process.stdin.pause();
+      };
+
+      if (process.stdin.isTTY) {
+        process.stdin.setRawMode(true);
+      }
+      process.stdin.resume();
+      process.stdin.on('data', onData);
+    });
+  }
+
+
+  footer(duration) {
+    this.log(`${this._dim('time')} ${this._rgb(COLORS.main, duration + 's')}`);
+  }
+
+  /**
+   * Restore cursor and stop timer. Safe to call from SIGINT / uncaughtException.
    */
-  render() {
-    const dots = this.frames[this.currentFrame];
-    // Renders the text followed by the cycling dots
-    process.stdout.write(`\r\x1b[K${formatSecondary(`${this.text}${dots}`)}`);
+  cleanup() {
+    this._abort();
+    this._showCursor();
   }
 }
 
-export const spinner = new Spinner();
+// Singleton — import { ui } wherever you need the terminal interface.
+export const ui = new UIEngine();