shortcutxl 0.2.0

package/dist/custom/tools/cron.js

@@ -0,0 +1,413 @@
+/**
+ * Cron tool — manage scheduled jobs via the agent.
+ *
+ * Actions: status, list, add, update, remove, run, history, daemon_start, daemon_stop.
+ * All actions read/write jobs.json directly (no daemon needed for CRUD).
+ */
+import { Type } from '@sinclair/typebox';
+import { CRON } from '../../tool-names.js';
+import { getDaemonStatus, isDaemonRunning, startDaemon, stopDaemon } from '../cron/daemon-ipc.js';
+import { applyJobPatch, createJob, normalizeJobState } from '../cron/jobs.js';
+import { readRunLog } from '../cron/run-log.js';
+import { computeNextRunAtMs } from '../cron/schedule.js';
+import { getCronStorePath, loadCronStore, saveCronStore } from '../cron/store.js';
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+const ScheduleSchema = Type.Union([
+    Type.Object({
+        kind: Type.Literal('at'),
+        at: Type.String({ description: 'ISO-8601 timestamp, e.g. "2026-03-06T17:00:00Z"' })
+    }),
+    Type.Object({
+        kind: Type.Literal('every'),
+        everyMs: Type.Number({ description: 'Interval in milliseconds, e.g. 1800000 for 30 minutes' })
+    }),
+    Type.Object({
+        kind: Type.Literal('cron'),
+        expr: Type.String({ description: 'Cron expression, e.g. "0 8 * * *" for daily at 8am' }),
+        tz: Type.Optional(Type.String({
+            description: 'IANA timezone, e.g. "America/New_York". Defaults to system timezone.'
+        }))
+    })
+]);
+const JobInputSchema = Type.Object({
+    name: Type.String({ description: 'Short name for the job' }),
+    schedule: ScheduleSchema,
+    payload: Type.Object({
+        message: Type.String({ description: 'The prompt/instruction for the agent to execute' }),
+        model: Type.Optional(Type.String({ description: 'Model override, e.g. "shortcut/claude-opus-4-6"' }))
+    }),
+    enabled: Type.Optional(Type.Boolean({ description: 'Whether the job is enabled (default: true)' })),
+    description: Type.Optional(Type.String({ description: 'Longer description of what the job does' }))
+});
+const PatchSchema = Type.Object({
+    name: Type.Optional(Type.String()),
+    description: Type.Optional(Type.String()),
+    enabled: Type.Optional(Type.Boolean()),
+    schedule: Type.Optional(ScheduleSchema),
+    payload: Type.Optional(Type.Object({
+        message: Type.Optional(Type.String()),
+        model: Type.Optional(Type.String())
+    }))
+});
+const schema = Type.Object({
+    action: Type.Union([
+        Type.Literal('list'),
+        Type.Literal('add'),
+        Type.Literal('update'),
+        Type.Literal('remove'),
+        Type.Literal('run'),
+        Type.Literal('status'),
+        Type.Literal('history'),
+        Type.Literal('daemon_start'),
+        Type.Literal('daemon_stop')
+    ], { description: 'The action to perform' }),
+    job: Type.Optional(JobInputSchema),
+    jobId: Type.Optional(Type.String({ description: 'Job ID for update/remove/run' })),
+    patch: Type.Optional(PatchSchema),
+    includeDisabled: Type.Optional(Type.Boolean({ description: 'Include disabled jobs in list (default: false)' })),
+    limit: Type.Optional(Type.Number({ description: 'Max entries to return for history (default: 5)' }))
+});
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function formatSchedule(schedule) {
+    if (schedule.kind === 'at')
+        return `at ${schedule.at}`;
+    if (schedule.kind === 'every')
+        return `every ${schedule.everyMs}ms`;
+    return `cron "${schedule.expr}"${schedule.tz ? ` (${schedule.tz})` : ''}`;
+}
+function formatJob(job) {
+    const status = job.enabled ? 'enabled' : 'disabled';
+    const schedule = formatSchedule(job.schedule);
+    const next = job.state.nextRunAtMs ? new Date(job.state.nextRunAtMs).toISOString() : 'none';
+    const lastStatus = job.state.lastRunStatus ?? 'never run';
+    const lastError = job.state.lastError ? ` — ${job.state.lastError}` : '';
+    return [
+        `  id: ${job.id}`,
+        `  name: ${job.name}`,
+        job.description ? `  description: ${job.description}` : null,
+        `  status: ${status}`,
+        `  schedule: ${schedule}`,
+        `  next run: ${next}`,
+        `  last: ${lastStatus}${lastError}`,
+        `  payload: ${job.payload.message}`
+    ]
+        .filter(Boolean)
+        .join('\n');
+}
+/** Try to recover flat params that weaker models produce (e.g. top-level name/schedule instead of nested job). */
+function recoverFlatParams(params) {
+    const p = { ...params };
+    if (p.action === 'add' && !p.job && typeof p.name === 'string') {
+        p.job = {
+            name: p.name,
+            schedule: p.schedule,
+            payload: (p.payload ?? { message: p.message }),
+            enabled: p.enabled,
+            description: p.description
+        };
+    }
+    if (p.action === 'update' && !p.jobId && typeof p.id === 'string') {
+        p.jobId = p.id;
+        // Recover flat patch fields
+        if (!p.patch) {
+            const patch = {};
+            if (typeof p.name === 'string')
+                patch.name = p.name;
+            if (typeof p.description === 'string')
+                patch.description = p.description;
+            if (typeof p.enabled === 'boolean')
+                patch.enabled = p.enabled;
+            if (p.schedule)
+                patch.schedule = p.schedule;
+            if (Object.keys(patch).length > 0)
+                p.patch = patch;
+        }
+    }
+    if ((p.action === 'remove' || p.action === 'run') && !p.jobId && typeof p.id === 'string') {
+        p.jobId = p.id;
+    }
+    return p;
+}
+// ---------------------------------------------------------------------------
+// Action handlers
+// ---------------------------------------------------------------------------
+async function handleStatus(storePath) {
+    const store = await loadCronStore(storePath);
+    const now = Date.now();
+    const enabled = store.jobs.filter((j) => j.enabled);
+    const nextRun = enabled
+        .map((j) => j.state.nextRunAtMs)
+        .filter((ms) => typeof ms === 'number')
+        .sort((a, b) => a - b)[0];
+    const running = store.jobs.filter((j) => typeof j.state.runningAtMs === 'number');
+    const daemon = getDaemonStatus();
+    const lines = [
+        `Daemon: ${daemon.running ? `running (pid ${daemon.pid})` : 'stopped'}`,
+        `Jobs: ${enabled.length} enabled, ${store.jobs.length - enabled.length} disabled`
+    ];
+    if (nextRun) {
+        const delta = Math.max(0, nextRun - now);
+        const mins = Math.round(delta / 60_000);
+        lines.push(`Next run: ${new Date(nextRun).toISOString()} (in ~${mins}m)`);
+    }
+    if (running.length > 0) {
+        lines.push(`Running: ${running.length} job(s)`);
+    }
+    if (!daemon.running && enabled.length > 0) {
+        lines.push('\nNote: daemon is not running. Use daemon_start to start it.');
+    }
+    return lines.join('\n');
+}
+async function handleHistory(storePath, jobId, limit) {
+    // Resolve job name for display
+    const store = await loadCronStore(storePath);
+    const job = store.jobs.find((j) => j.id === jobId);
+    const jobLabel = job ? `"${job.name}" (${jobId})` : jobId;
+    const entries = await readRunLog(jobId, limit);
+    if (entries.length === 0) {
+        return `No run history for ${jobLabel}.`;
+    }
+    const lines = [`Run history for ${jobLabel} (${entries.length} most recent):\n`];
+    for (const entry of entries) {
+        const date = new Date(entry.startedAtMs).toISOString();
+        const duration = `${entry.durationMs}ms`;
+        const status = entry.status === 'ok' ? '✓' : '✗';
+        lines.push(`${status} ${date} — ${entry.status} (${duration})`);
+        if (entry.error) {
+            lines.push(`  error: ${entry.error}`);
+        }
+        if (entry.output) {
+            // Show first ~500 chars of output inline
+            const preview = entry.output.length > 500 ? entry.output.slice(0, 500) + '...' : entry.output;
+            lines.push(`  output: ${preview}`);
+        }
+    }
+    return lines.join('\n');
+}
+async function handleDaemonStart() {
+    const { pid, alreadyRunning } = await startDaemon();
+    if (alreadyRunning) {
+        return `Cron daemon is already running (pid ${pid}).`;
+    }
+    return `Cron daemon started (pid ${pid}).`;
+}
+async function handleDaemonStop() {
+    const stopped = await stopDaemon();
+    return stopped ? 'Cron daemon stopped.' : 'Cron daemon was not running.';
+}
+async function handleList(storePath, includeDisabled) {
+    const store = await loadCronStore(storePath);
+    const now = Date.now();
+    let storeChanged = false;
+    for (const j of store.jobs) {
+        if (normalizeJobState(j, now))
+            storeChanged = true;
+    }
+    if (storeChanged)
+        await saveCronStore(storePath, store);
+    const jobs = includeDisabled ? store.jobs : store.jobs.filter((j) => j.enabled);
+    if (jobs.length === 0) {
+        return includeDisabled
+            ? 'No cron jobs.'
+            : 'No enabled cron jobs. Use includeDisabled to see all.';
+    }
+    return jobs.map((j) => formatJob(j)).join('\n\n');
+}
+async function handleAdd(storePath, input) {
+    const now = Date.now();
+    // Validate schedule before creating
+    try {
+        const nextRun = computeNextRunAtMs(input.schedule, now);
+        if (nextRun === undefined && input.schedule.kind === 'at') {
+            return 'Error: the "at" timestamp is in the past. Use a future timestamp.';
+        }
+    }
+    catch (err) {
+        return `Error: invalid schedule — ${err instanceof Error ? err.message : String(err)}`;
+    }
+    const jobCreate = {
+        name: input.name,
+        schedule: input.schedule,
+        payload: input.payload,
+        enabled: input.enabled ?? true,
+        description: input.description
+    };
+    const store = await loadCronStore(storePath);
+    const job = createJob(jobCreate, now);
+    store.jobs.push(job);
+    await saveCronStore(storePath, store);
+    let result = `Created job "${job.name}" (${job.id})\nSchedule: ${formatSchedule(job.schedule)}\nNext run: ${job.state.nextRunAtMs ? new Date(job.state.nextRunAtMs).toISOString() : 'none'}`;
+    // Auto-start daemon if not running
+    if (job.enabled && !isDaemonRunning()) {
+        try {
+            const { pid } = await startDaemon();
+            result += `\nDaemon started (pid ${pid}).`;
+        }
+        catch {
+            result += '\nNote: could not auto-start daemon. Use daemon_start manually.';
+        }
+    }
+    return result;
+}
+async function handleUpdate(storePath, jobId, patch) {
+    const store = await loadCronStore(storePath);
+    const job = store.jobs.find((j) => j.id === jobId);
+    if (!job)
+        return `Error: no job with id "${jobId}". Use the list action to see available jobs.`;
+    const now = Date.now();
+    // Validate new schedule if provided
+    if (patch.schedule) {
+        try {
+            const nextRun = computeNextRunAtMs(patch.schedule, now);
+            if (nextRun === undefined && patch.schedule.kind === 'at') {
+                return 'Error: the "at" timestamp is in the past. Use a future timestamp.';
+            }
+        }
+        catch (err) {
+            return `Error: invalid schedule — ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    applyJobPatch(job, patch, now);
+    await saveCronStore(storePath, store);
+    return `Updated job "${job.name}" (${job.id})\n${formatJob(job)}`;
+}
+async function handleRemove(storePath, jobId) {
+    const store = await loadCronStore(storePath);
+    const idx = store.jobs.findIndex((j) => j.id === jobId);
+    if (idx === -1)
+        return `Error: no job with id "${jobId}".`;
+    const removed = store.jobs.splice(idx, 1)[0];
+    await saveCronStore(storePath, store);
+    return `Removed job "${removed.name}" (${removed.id}).`;
+}
+async function handleRun(storePath, jobId) {
+    const store = await loadCronStore(storePath);
+    const job = store.jobs.find((j) => j.id === jobId);
+    if (!job)
+        return `Error: no job with id "${jobId}".`;
+    if (!job.enabled)
+        return `Error: job "${job.name}" is disabled. Enable it first.`;
+    if (typeof job.state.runningAtMs === 'number')
+        return `Job "${job.name}" is already running.`;
+    const now = Date.now();
+    // Mark as due so the daemon picks it up on next tick
+    job.state.runningAtMs = undefined;
+    job.state.nextRunAtMs = now - 1; // Force due
+    await saveCronStore(storePath, store);
+    if (!isDaemonRunning()) {
+        return `Triggered job "${job.name}" (${job.id}), but the daemon is not running. Use daemon_start first.`;
+    }
+    return `Triggered job "${job.name}" (${job.id}). It will execute on the next daemon tick.`;
+}
+// ---------------------------------------------------------------------------
+// Tool description
+// ---------------------------------------------------------------------------
+const TOOL_DESCRIPTION = `\
+Manage cron jobs — scheduled tasks that run automatically.
+
+**Actions:**
+- \`status\` — Show job count and next fire time
+- \`list\` — List jobs (set includeDisabled=true to see disabled ones)
+- \`add\` — Create a new scheduled job
+- \`update\` — Modify an existing job (requires jobId + patch)
+- \`remove\` — Delete a job (requires jobId)
+- \`run\` — Force a job to run on the next daemon tick (requires jobId)
+- \`history\` — View recent run results with output (requires jobId, optional limit)
+- \`daemon_start\` — Start the background scheduler
+- \`daemon_stop\` — Stop the scheduler
+
+**Schedule types:**
+- \`at\`: one-shot at a specific time — \`{ kind: "at", at: "2026-03-06T17:00:00Z" }\`
+- \`every\`: recurring interval — \`{ kind: "every", everyMs: 1800000 }\` (30 minutes)
+- \`cron\`: cron expression — \`{ kind: "cron", expr: "0 8 * * *" }\` (daily at 8am)
+
+**Examples:**
+- "every morning at 8am" → schedule: \`{ kind: "cron", expr: "0 8 * * *" }\`
+- "every 30 minutes" → schedule: \`{ kind: "every", everyMs: 1800000 }\`
+- "at 5pm today" → schedule: \`{ kind: "at", at: "<today>T17:00:00Z" }\` (use actual date)
+- "every weekday at 9am ET" → schedule: \`{ kind: "cron", expr: "0 9 * * 1-5", tz: "America/New_York" }\`
+`;
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+export function createCronTool(storePath = getCronStorePath()) {
+    return {
+        name: CRON,
+        label: 'Cron',
+        description: TOOL_DESCRIPTION,
+        parameters: schema,
+        async execute(_toolCallId, rawParams, _signal, _onUpdate, _ctx) {
+            const params = recoverFlatParams(rawParams);
+            let text;
+            switch (params.action) {
+                case 'status':
+                    text = await handleStatus(storePath);
+                    break;
+                case 'list':
+                    text = await handleList(storePath, params.includeDisabled ?? false);
+                    break;
+                case 'add': {
+                    if (!params.job) {
+                        text = 'Error: "add" action requires a "job" object with name, schedule, and payload.';
+                        break;
+                    }
+                    text = await handleAdd(storePath, params.job);
+                    break;
+                }
+                case 'update': {
+                    if (!params.jobId) {
+                        text = 'Error: "update" action requires "jobId".';
+                        break;
+                    }
+                    if (!params.patch) {
+                        text = 'Error: "update" action requires a "patch" object.';
+                        break;
+                    }
+                    text = await handleUpdate(storePath, params.jobId, params.patch);
+                    break;
+                }
+                case 'remove': {
+                    if (!params.jobId) {
+                        text = 'Error: "remove" action requires "jobId".';
+                        break;
+                    }
+                    text = await handleRemove(storePath, params.jobId);
+                    break;
+                }
+                case 'run': {
+                    if (!params.jobId) {
+                        text = 'Error: "run" action requires "jobId".';
+                        break;
+                    }
+                    text = await handleRun(storePath, params.jobId);
+                    break;
+                }
+                case 'history': {
+                    if (!params.jobId) {
+                        text = 'Error: "history" action requires "jobId".';
+                        break;
+                    }
+                    text = await handleHistory(storePath, params.jobId, params.limit ?? 5);
+                    break;
+                }
+                case 'daemon_start':
+                    text = await handleDaemonStart();
+                    break;
+                case 'daemon_stop':
+                    text = await handleDaemonStop();
+                    break;
+                default:
+                    text = `Unknown action "${params.action}". Valid actions: status, list, add, update, remove, run, history, daemon_start, daemon_stop.`;
+            }
+            return {
+                content: [{ type: 'text', text }],
+                details: undefined
+            };
+        }
+    };
+}
+//# sourceMappingURL=cron.js.map

package/dist/custom/tools/excel-exec.js

@@ -0,0 +1,167 @@
+/**
+ * Excel exec tool — POST /exec with Python code to ShortcutXL's HTTP server.
+ *
+ * Request:  POST /exec  { "code": "..." }
+ * Response: { "ok": true, "output": "..." } or { "ok": false, "error": "..." }
+ */
+import { Type } from '@sinclair/typebox';
+import { truncateOutput } from '../../core/tools/truncate.js';
+import { EXCEL_EXEC } from '../../tool-names.js';
+import { Text } from '../../tui/index.js';
+import { formatNotation, parseExcelLocation } from './excel-range.js';
+import { highlightCode } from './render-helpers.js';
+const TOOL_NAME = EXCEL_EXEC;
+/**
+ * Wraps user code so it runs inside managed_app() without any
+ * indentation changes (which would corrupt multiline strings).
+ *
+ * We compile the user code separately and exec() it, passing `app`
+ * from the context manager into the exec namespace.
+ */
+/** Sentinels used to separate structured data from agent stdout. */
+const DIRTY_CELLS_MARKER = '\n__DIRTY_CELLS_JSON__';
+const DIFF_SUMMARY_MARKER = '\n__DIFF_SUMMARY__';
+const NO_OUTPUT_FALLBACK = '(no output)';
+const NO_CHANGES_MSG = 'No changes made.';
+function wrapCode(userCode) {
+    // JSON.stringify produces a valid Python string literal (both use the
+    // same escape sequences for \n, \t, \\, \", and Unicode \uXXXX).
+    const codeLiteral = JSON.stringify(userCode);
+    return [
+        'from shortcut_xl import run_managed as _run_managed, format_cell_diff as _format_diff',
+        'import json as _json',
+        `_code = compile(${codeLiteral}, "<excel_exec>", "exec")`,
+        'def _fn(app):',
+        '    _ns = {**globals(), "app": app}',
+        '    exec(_code, _ns)',
+        '_dirty = _run_managed(_fn)',
+        'print("\\n__DIRTY_CELLS_JSON__" + _json.dumps(_dirty, default=str))',
+        'print("\\n__DIFF_SUMMARY__" + _format_diff(_dirty))'
+    ].join('\n');
+}
+/** What the LLM sees — hides the context-manager wrapper. */
+const VISIBLE_PREAMBLE = `from shortcut_xl import xl_app\napp = xl_app()\n`;
+const TOOL_DESCRIPTION = `\
+Execute Python code in Excel via ShortcutXL.
+The code runs in-process with access to the Excel COM API via app (an Excel.Application COM object, same API as VBA).
+Stdout/stderr are captured. Use print() to return values.
+
+\`\`\`python
+${VISIBLE_PREAMBLE}
+\`\`\`
+
+is auto-prepended — do NOT include it in your code.
+
+**Code discipline:**
+- Keep each code block under 100 lines — errors accumulate quickly in long blocks.
+- Minimize comments. Use print() statements for inspection, and keep them concise.
+- For read operations, prefer reading large ranges to grab richer context instead of iteratively reading small ranges.
+- Your code should be simple and efficient. Minimize code duplication.
+- Stop retrying after 2 attempts for unexplained failures.
+`;
+const schema = Type.Object({
+    description: Type.String({
+        description: 'Short description of what the code does for non-technical users. You MUST reference ranges for any read / write operation. Use this notation for reads and writes, including the bracekts: <Workbook:Sheet!Range>. Omit range if operating on the whole sheet or workbook.'
+    }),
+    code: Type.String({
+        description: 'Python code to execute in Excel. `app` (Excel.Application) is already available — do NOT import xl_app. Use print() to return values.'
+    })
+});
+export function createExcelExecTool(httpUrl) {
+    return {
+        name: TOOL_NAME,
+        label: 'Excel exec',
+        description: TOOL_DESCRIPTION,
+        parameters: schema,
+        renderCall(args, options, theme) {
+            const desc = typeof args?.description === 'string' ? args.description : '';
+            const code = typeof args?.code === 'string' ? args.code : '';
+            // Highlight the Excel reference in accent color
+            let label = desc || 'excel_exec';
+            const loc = desc ? parseExcelLocation(desc) : null;
+            if (loc) {
+                const notation = formatNotation(loc);
+                if (notation) {
+                    const styled = theme.fg('accent', notation);
+                    const bracketedIdx = label.indexOf(`<${notation}>`);
+                    if (bracketedIdx >= 0) {
+                        label = label.replace(`<${notation}>`, styled);
+                    }
+                    else {
+                        label = label.replace(notation, styled);
+                    }
+                }
+            }
+            const title = theme.fg('toolTitle', theme.bold(`𝕏 ${label}`));
+            if (!options.expanded) {
+                return new Text(title, 0, 0);
+            }
+            if (!code) {
+                return new Text(`${title}\n\n${theme.fg('toolOutput', '...')}`, 0, 0);
+            }
+            const highlighted = highlightCode(code, 'python');
+            return new Text(`${title}\n\n${highlighted.join('\n')}`, 0, 0);
+        },
+        renderResult(result, options, theme) {
+            if (!options.expanded)
+                return undefined;
+            const textBlocks = result.content?.filter((c) => c.type === 'text') || [];
+            const output = textBlocks.map((c) => ('text' in c ? c.text : '') || '').join('\n');
+            if (!output)
+                return undefined;
+            return new Text(theme.fg('toolOutput', output), 0, 0);
+        },
+        async execute(_toolCallId, { code, description }, signal, _onUpdate, _ctx) {
+            const fullCode = wrapCode(code);
+            let response;
+            try {
+                response = await fetch(`${httpUrl}/exec`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ code: fullCode }),
+                    signal
+                });
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                throw new Error(`Failed to connect to Excel at ${httpUrl}: ${msg}`);
+            }
+            const result = (await response.json());
+            if (!result.ok) {
+                throw new Error(result.error ?? 'Unknown error from Excel');
+            }
+            // Extract diff summary and dirty cells from stdout (appended by wrapCode)
+            let output = result.output ?? NO_OUTPUT_FALLBACK;
+            let dirtyCells = [];
+            let diffSummary = '';
+            // Extract diff summary first (it comes after dirty cells JSON)
+            const summaryIdx = output.indexOf(DIFF_SUMMARY_MARKER);
+            if (summaryIdx !== -1) {
+                diffSummary = output.slice(summaryIdx + DIFF_SUMMARY_MARKER.length).trim();
+                output = output.slice(0, summaryIdx);
+            }
+            // Extract dirty cells JSON
+            const markerIdx = output.indexOf(DIRTY_CELLS_MARKER);
+            if (markerIdx !== -1) {
+                const jsonStr = output.slice(markerIdx + DIRTY_CELLS_MARKER.length).trim();
+                output = output.slice(0, markerIdx).trimEnd() || NO_OUTPUT_FALLBACK;
+                try {
+                    dirtyCells = JSON.parse(jsonStr);
+                }
+                catch {
+                    // Best-effort — if parsing fails, just skip dirty cells
+                }
+            }
+            result.dirtyCells = dirtyCells;
+            // Append the formatted diff summary to the visible output
+            if (diffSummary && diffSummary !== NO_CHANGES_MSG) {
+                output = output + '\n\n' + diffSummary;
+            }
+            return {
+                content: [{ type: 'text', text: truncateOutput(output) }],
+                details: result
+            };
+        }
+    };
+}
+//# sourceMappingURL=excel-exec.js.map

package/dist/custom/tools/excel-range.js

@@ -0,0 +1,50 @@
+/**
+ * Excel range parsing utilities.
+ *
+ * Parses <Workbook:Sheet!Range> notation from excel_exec descriptions.
+ */
+/**
+ * Extract Excel location from the <...> bracket in a description string.
+ * Returns null if no bracketed reference is found.
+ */
+export function parseExcelLocation(description) {
+    const m = description.match(/<([^>]+)>/);
+    if (!m)
+        return null;
+    const ref = m[1].trim();
+    // Workbook:Sheet!Range
+    const full = ref.match(/^([^:]+):([^!]+)!(.+)$/);
+    if (full) {
+        return { workbook: full[1].trim(), sheet: full[2].trim(), range: full[3].trim() };
+    }
+    // Sheet!Range
+    const sr = ref.match(/^([^!]+)!(.+)$/);
+    if (sr) {
+        return { sheet: sr[1].trim(), range: sr[2].trim() };
+    }
+    // Bare range (e.g. A1:D10, A1) — check before Workbook:Sheet since "A1:D10" has a colon
+    if (/^[A-Z]{1,3}\d+(?::[A-Z]{1,3}\d+)?$/.test(ref)) {
+        return { range: ref };
+    }
+    // Workbook:Sheet (no range)
+    const ws = ref.match(/^([^:]+):(.+)$/);
+    if (ws) {
+        return { workbook: ws[1].trim(), sheet: ws[2].trim() };
+    }
+    return ref ? { sheet: ref } : null;
+}
+/**
+ * Reconstruct the original notation: Workbook:Sheet!Range.
+ * Used for string replacement in renderCall labels.
+ */
+export function formatNotation(loc) {
+    let s = '';
+    if (loc.workbook)
+        s += loc.workbook;
+    if (loc.sheet)
+        s += (s ? ':' : '') + loc.sheet;
+    if (loc.range)
+        s += (s ? '!' : '') + loc.range;
+    return s;
+}
+//# sourceMappingURL=excel-range.js.map