shortcutxl 0.2.14 → 0.2.15

package/README.md

@@ -1,13 +1,33 @@
 # ShortcutXL
 
-An AI agent that lives on your computer and has Excel superpowers. Made by the Shortcut team [Shortcut](https://shortcut.ai).
+An AI agent that lives on your computer and has Excel superpowers. Made by the [Shortcut](https://shortcut.ai) team.
+
+## Install
+
+### 1. Open Command Prompt or PowerShell and install Node.js
+
+```bash
+winget install OpenJS.NodeJS.LTS
+```
+
+### 2. Install ShortcutXL
 
 ```bash
 npm install -g shortcutxl
+```
+
+### 3. Launch ShortcutXL
+
+Type `shortcut` in your terminal:
+
+```bash
 shortcut
 ```
 
-> **Important:** Install globally with `-g`. Do not use `npm install shortcutxl` without it.
+## Requirements
+
+- **Windows 10/11** with **Excel 2016+** (64-bit)
+- **Node.js >= 20**
 
 ## Capabilities
 
@@ -19,8 +39,3 @@ shortcut
 - **Extensible** — Integrate any API or data source by adding a skill file or a custom tool extension.
 - **User-defined functions (UDFs)** — Custom Excel formulas powered by Python for live data, calculations, or database queries.
 - **External data connections** — ODBC, OLE DB, QueryTables, Power Query.
-
-## Prerequisites
-
-- **Windows 10/11** with **Excel 2016+** (64-bit)
-- **Node.js >= 20** — If missing: `winget install OpenJS.NodeJS.LTS`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shortcutxl",
-  "version": "0.2.14",
+  "version": "0.2.15",
   "type": "module",
   "files": [
     "dist/",

package/xll/modules/shortcut_xl/_exec_entry.py

@@ -4,8 +4,8 @@ C calls dispatch_request(body_json) for every POST /exec.
 This function always returns valid JSON. C never builds JSON.
 
 Two request shapes:
-  {"code": "..."}                              → exec_and_respond
-  {"control": "revert"|"cleanup", "cfTxId": "..."} → handle_control
+  {"code": "..."}                                        → exec_and_respond
+  {"control": "revert"|"cleanup"|"navigate", ...}        → handle_control
 """
 
 import io
@@ -20,7 +20,9 @@ from shortcut_xl._diff_highlight import (
     revert_by_tx,
 )
 from shortcut_xl._managed import run_managed
+from shortcut_xl._navigate import clear_navigate_cursor, navigate_to_cell
 from shortcut_xl._threading import _run_on_main
+from shortcut_xl.api.utils.helpers import address_to_index
 
 _MAX_DIFF_JSON_CELLS = 50
 
@@ -44,12 +46,41 @@ def _format_cell_value(v):
         return str(v)
 
 
+def _cell_sort_key(c):
+    """Sort key: (sheet, row, col) using address_to_index."""
+    addr = c.get('address', '')
+    try:
+        row, col = address_to_index(addr)
+    except (ValueError, AttributeError):
+        row, col = 0, 0
+    return (c.get('sheet', ''), row, col)
+
+
+def _sort_dirty(dirty):
+    """Sort dirty cells by (sheet, row, column) for row-wise display.
+
+    Applied once before both _build_diff and highlight_changes so the
+    entire pipeline sees a consistent order.
+    """
+    return sorted(dirty, key=_cell_sort_key)
+
+
+def _cell_ref(c):
+    """Build a full cell reference string from a dirty cell dict."""
+    wb = c.get('workbook', '')
+    prefix = f"[{wb}]" if wb else ''
+    return f"{prefix}{c.get('sheet', '')}!{c.get('address', '')}"
+
+
 def _build_diff(dirty):
-    """Build structured diff payload for the TUI approval component."""
+    """Build structured diff payload for the TUI approval component.
+
+    Expects *dirty* to be pre-sorted by _sort_dirty. One row per cell.
+    """
     cells = []
     for c in dirty[:_MAX_DIFF_JSON_CELLS]:
         entry = {
-            'cell': f"{c.get('sheet', '')}!{c.get('address', '')}",
+            'address': _cell_ref(c),
             'before': _format_cell_value(c.get('oldValue')),
             'after': _format_cell_value(c.get('value')),
         }
@@ -109,6 +140,7 @@ def exec_and_respond(code_str, *, auto_approve=False):
 
         response = {'ok': True, 'output': output}
         if dirty:
+            dirty = _sort_dirty(dirty)
             response['diff'] = _build_diff(dirty)
             # Only apply CF highlights when the user may review changes.
             if not auto_approve:
@@ -136,12 +168,21 @@ def handle_control(request):
     if action == 'revert':
         if cf_tx_id is None:
             return json.dumps({'ok': False, 'error': "revert requires cfTxId"})
+        _run_on_main(clear_navigate_cursor)
         n = _run_on_main(lambda: revert_by_tx(xl_app(), cf_tx_id))
         if n == 0:
             return json.dumps({'ok': True, 'output': 'Nothing to revert (transaction not found or already cleaned up).'})
         return json.dumps({'ok': True, 'output': f"Reverted {n} cell{'s' if n != 1 else ''}."})
 
+    elif action == 'navigate':
+        cell_ref = request.get('cellRef', '')
+        if not cell_ref:
+            return json.dumps({'ok': False, 'error': "navigate requires cellRef"})
+        ok = _run_on_main(lambda: navigate_to_cell(xl_app(), cell_ref))
+        return json.dumps({'ok': ok, 'output': '' if ok else f"Could not navigate to {cell_ref}"})
+
     elif action == 'cleanup':
+        _run_on_main(clear_navigate_cursor)
         if cf_tx_id is not None:
             _run_on_main(lambda: cleanup_by_tx(cf_tx_id))
         return json.dumps({'ok': True, 'output': ''})

package/xll/modules/shortcut_xl/_navigate.py

@@ -0,0 +1,115 @@
+"""Navigate Excel to a specific cell — used during diff review.
+
+Highlights the cursor cell with a colored border via direct Range
+formatting. Visible even when Excel doesn't have focus (unlike
+.Select() which only shows when Excel is foreground).
+
+Thread safety: called via _run_on_main, serialized by s_exec_lock.
+"""
+
+from shortcut_xl._log import xl_log
+from shortcut_xl.api.utils.helpers import extract_sheet_and_range
+
+# Excel COM constants
+_XL_EDGE_LEFT = 7
+_XL_EDGE_TOP = 8
+_XL_EDGE_BOTTOM = 9
+_XL_EDGE_RIGHT = 10
+_XL_CONTINUOUS = 1
+_XL_LINE_STYLE_NONE = -4142
+_XL_MEDIUM = -4138
+
+_CURSOR_BLUE = 0xFF0000    # BGR — distinct from yellow change highlights
+_BORDER_EDGES = (_XL_EDGE_LEFT, _XL_EDGE_TOP, _XL_EDGE_BOTTOM, _XL_EDGE_RIGHT)
+
+# Current cursor state — at most one cell highlighted at a time.
+_cursor_ws = None       # COM Worksheet of the current cursor cell
+_cursor_address = None  # e.g. "B5"
+
+
+def parse_cell_ref(cell_ref):
+    """Parse a cell reference into (workbook, sheet, address).
+
+    Supports single cells and ranges:
+      "[Book1]Sheet1!A1"     → ("Book1", "Sheet1", "A1")
+      "Sheet1!A1:E1"         → (None,    "Sheet1", "A1:E1")
+
+    Returns (None, None, None) if the reference is invalid.
+    """
+    rest = cell_ref
+    workbook = None
+
+    if rest.startswith('['):
+        close = rest.find(']')
+        if close <= 1:          # missing or empty workbook name
+            return None, None, None
+        workbook = rest[1:close]
+        rest = rest[close + 1:]
+
+    sheet, address = extract_sheet_and_range(rest)
+    if not sheet or not address:
+        return None, None, None
+
+    return workbook, sheet, address
+
+
+def _resolve_worksheet(app, workbook, sheet):
+    """Get the COM Worksheet object for the given workbook/sheet names."""
+    if workbook:
+        return app.Workbooks(workbook).Worksheets(sheet)
+    return app.Worksheets(sheet)
+
+
+def _set_border(rng, color, line_style, weight):
+    """Apply border styling to all four edges of a range."""
+    for edge in _BORDER_EDGES:
+        b = rng.Borders(edge)
+        b.LineStyle = line_style
+        if line_style != _XL_LINE_STYLE_NONE:
+            b.Color = color
+            b.Weight = weight
+
+
+def _clear_cursor():
+    """Remove the border from the current cursor cell, if any."""
+    global _cursor_ws, _cursor_address
+    if _cursor_ws is None or _cursor_address is None:
+        return
+    try:
+        _set_border(_cursor_ws.Range(_cursor_address), 0, _XL_LINE_STYLE_NONE, 0)
+    except Exception as e:
+        xl_log(f"_clear_cursor({_cursor_address}): {e}")
+    _cursor_ws = None
+    _cursor_address = None
+
+
+def navigate_to_cell(app, cell_ref):
+    """Highlight the cell with a colored border.
+
+    *cell_ref* is "[Book1]Sheet1!A1" or "Sheet1!A1".
+    Clears the previous cursor border before applying the new one.
+    Returns True on success, False on failure.
+    """
+    global _cursor_ws, _cursor_address
+
+    workbook, sheet, address = parse_cell_ref(cell_ref)
+    if not sheet or not address:
+        return False
+
+    _clear_cursor()
+
+    try:
+        ws = _resolve_worksheet(app, workbook, sheet)
+        rng = ws.Range(address)
+        _set_border(rng, _CURSOR_BLUE, _XL_CONTINUOUS, _XL_MEDIUM)
+        _cursor_ws = ws
+        _cursor_address = address
+        return True
+    except Exception as e:
+        xl_log(f"navigate_to_cell({cell_ref}): {e}")
+        return False
+
+
+def clear_navigate_cursor():
+    """Remove the cursor border. Called on approval accept/reject."""
+    _clear_cursor()

package/xll/modules/shortcut_xl/_tracking.py

@@ -142,8 +142,14 @@ class DirtyTracker:
             try:
                 after = _SheetSnapshot(ws)
                 changes = _diff_snapshots(name, before, after)
-                # Enrich with numberFormat (can't bulk-read mixed ranges)
+                # Enrich with workbook name + numberFormat
+                try:
+                    wb_name = ws.Parent.Name
+                except Exception:
+                    wb_name = None
                 for entry in changes:
+                    if wb_name:
+                        entry['workbook'] = wb_name
                     try:
                         fmt = ws.Range(entry['address']).NumberFormat
                         if fmt and fmt != 'General':