@sheetxl/utils-node 0.8.0-beta.9 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE.md CHANGED
@@ -1,11 +1,21 @@
1
- # Repository Licensing
1
+ MIT License
2
2
 
3
- SheetXL contains a mix of open-source and commercially licensed packages. Each package is individually licensed and contains its own license file.
3
+ Copyright (c) 2026-present SheetXL Inc. & Michael T. Ford
4
4
 
5
- For the specific terms and conditions applicable to a package, please see the `LICENSE.md` file located in that package's root directory.
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
6
11
 
7
- Generally, packages intended for public distribution (such as CLIs, adapters, and vanilla wrappers) are licensed under the MIT license. All other core packages are proprietary and require a commercial license for use.
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
8
14
 
9
- For more details on commercial licensing, please visit our website:
10
-
11
- https://www.sheetxl.com/docs/guides/licensing-pricing
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -1,39 +1,39 @@
1
1
  /**
2
- * @license @sheetxl/utils-node - SheetXL - Node-only utilities: terminal presentation, environment reporting, tool logging - v0.8.0-beta.9
2
+ * @license @sheetxl/utils-node - SheetXL - Node-only utilities: terminal presentation, environment reporting, tool logging - v1.0.2
3
3
  *
4
4
  * (C) 2026-present SheetXL Inc. & Michael T. Ford
5
- * License: The license can be found at https://www.sheetxl.com/license.
5
+ * License: MIT
6
6
  */
7
7
  import { createRequire as e } from "node:module";
8
8
  import t from "chalk";
9
9
  import * as n from "node:os";
10
10
  import * as s from "node:path";
11
- import { existsSync as o, readFileSync as r } from "node:fs";
12
- import { appendFile as i, mkdir as a, readFile as l, readdir as c, stat as u, unlink as h, writeFile as d } from "node:fs/promises";
13
- import { fileURLToPath as p } from "node:url";
14
- import { createHash as f } from "node:crypto";
15
- var m = (e) => /^#{1,4} /.test(e) ? t.cyan.bold(e) : ((e) => e.replace(/`([^`]+)`/g, (e, n) => t.yellow(n)).replace(/\*\*([^*]+)\*\*/g, (e, n) => t.bold(n)).replace(/(?<=^|\s)_([^_\s](?:[^_]*[^_\s])?)_(?=[\s.,)]|$)/g, (e, n) => t.italic(n)))(e), v = (e, t) => {
11
+ import { existsSync as o, readFileSync as r, readdirSync as i } from "node:fs";
12
+ import { appendFile as a, mkdir as l, readFile as c, readdir as u, stat as h, unlink as d, writeFile as p } from "node:fs/promises";
13
+ import { fileURLToPath as f } from "node:url";
14
+ import { createHash as m } from "node:crypto";
15
+ var g = (e) => /^#{1,4} /.test(e) ? t.cyan.bold(e) : ((e) => e.replace(/`([^`]+)`/g, (e, n) => t.yellow(n)).replace(/\*\*([^*]+)\*\*/g, (e, n) => t.bold(n)).replace(/(?<=^|\s)_([^_\s](?:[^_]*[^_\s])?)_(?=[\s.,)]|$)/g, (e, n) => t.italic(n)))(e), v = (e, t) => {
16
16
  const n = t?.stream ?? process.stdout;
17
- n.write(g(e.endsWith("\n") ? e : e + "\n", n));
18
- }, g = (e, t = process.stdout) => t.isTTY ? e.split("\n").map(m).join("\n") : e;
19
- function w(e) {
17
+ n.write(w(e.endsWith("\n") ? e : e + "\n", n));
18
+ }, w = (e, t = process.stdout) => t.isTTY ? e.split("\n").map(g).join("\n") : e;
19
+ function y(e) {
20
20
  const t = new Date(e);
21
21
  if (Number.isNaN(t.getTime())) return e;
22
22
  const n = (e) => String(e).padStart(2, "0");
23
23
  return `${t.getFullYear()}-${n(t.getMonth() + 1)}-${n(t.getDate())} ${n(t.getHours())}:${n(t.getMinutes())}`;
24
24
  }
25
- function y(e, t) {
26
- return e && "local" !== e ? e : t ? `local ${w(t)}` : "local";
25
+ function k(e, t) {
26
+ return e && "local" !== e ? e : t ? `local ${y(t)}` : "local";
27
27
  }
28
- var k = () => s.join(n.homedir(), ".sheetxl", "locks");
28
+ var x = () => s.join(n.homedir(), ".sheetxl", "locks");
29
29
  async function $(e) {
30
30
  try {
31
- return JSON.parse(await l(e, "utf-8"));
31
+ return JSON.parse(await c(e, "utf-8"));
32
32
  } catch {
33
33
  return null;
34
34
  }
35
35
  }
36
- async function x(e) {
36
+ async function j(e) {
37
37
  try {
38
38
  return (await fetch(`http://127.0.0.1:${e.port}/sheetxl-mcp/ping`, {
39
39
  headers: { Authorization: `Bearer ${e.token}` },
@@ -43,104 +43,143 @@ async function x(e) {
43
43
  return !1;
44
44
  }
45
45
  }
46
- async function j() {
46
+ async function b() {
47
47
  const e = (() => {
48
- const e = process.env.SHEETXL_WORKSPACE ?? process.cwd(), t = f("sha256").update(e).digest("hex").slice(0, 8);
49
- return s.join(k(), `${t}.lock`);
48
+ const e = process.env.SHEETXL_WORKSPACE ?? process.cwd(), t = m("sha256").update(e).digest("hex").slice(0, 8);
49
+ return s.join(x(), `${t}.lock`);
50
50
  })(), t = await $(e);
51
51
  if (t) {
52
- if (await x(t)) return t;
53
- await h(e).catch(() => {});
52
+ if (await j(t)) return t;
53
+ await d(e).catch(() => {});
54
54
  }
55
55
  return async function() {
56
56
  let e;
57
57
  try {
58
- e = (await c(k())).filter((e) => e.endsWith(".lock"));
58
+ e = (await u(x())).filter((e) => e.endsWith(".lock"));
59
59
  } catch {
60
60
  return null;
61
61
  }
62
62
  if (!e.length) return null;
63
63
  const t = await Promise.all(e.map(async (e) => ({
64
64
  f: e,
65
- mtime: (await u(s.join(k(), e))).mtimeMs
65
+ mtime: (await h(s.join(x(), e))).mtimeMs
66
66
  })));
67
67
  t.sort((e, t) => t.mtime - e.mtime);
68
68
  for (const { f: e } of t) {
69
- const t = s.join(k(), e), n = await $(t);
69
+ const t = s.join(x(), e), n = await $(t);
70
70
  if (n) {
71
- if (await x(n)) return n;
72
- await h(t).catch(() => {});
71
+ if (await j(n)) return n;
72
+ await d(t).catch(() => {});
73
73
  }
74
74
  }
75
75
  return null;
76
76
  }();
77
77
  }
78
- async function b(e) {
78
+ async function S(e) {
79
79
  return await (await fetch(`http://127.0.0.1:${e.port}/sheetxl-mcp/relay-workbooks`, {
80
80
  headers: { Authorization: `Bearer ${e.token}` },
81
81
  signal: AbortSignal.timeout(2e3)
82
82
  })).json();
83
83
  }
84
- var S = () => s.join(n.homedir(), ".sheetxl", "cache", "update.json");
85
- async function A(e = Date.now()) {
86
- const t = await async function() {
84
+ var A = () => s.join(n.homedir(), ".sheetxl", "cache", "update.json");
85
+ function O(e, t) {
86
+ const n = e.includes("-") ? ["beta", "latest"] : ["latest"];
87
+ let s = null;
88
+ for (const e of n) {
89
+ const n = t[e];
90
+ n && (!s || N(n, s.latest) > 0) && (s = {
91
+ latest: n,
92
+ tag: e
93
+ });
94
+ }
95
+ return s;
96
+ }
97
+ async function C(e, t = Date.now()) {
98
+ const n = (t, n) => {
99
+ const s = O(e, t);
100
+ return s ? {
101
+ ...s,
102
+ cacheStatus: n
103
+ } : {
104
+ latest: null,
105
+ tag: null,
106
+ cacheStatus: "missing"
107
+ };
108
+ }, o = await async function() {
87
109
  try {
88
- const e = JSON.parse(await l(S(), "utf-8"));
89
- return "string" != typeof e?.latest || "number" != typeof e?.checkedAt ? null : e;
110
+ const e = JSON.parse(await c(A(), "utf-8"));
111
+ return "object" == typeof e?.tags && e.tags && "number" == typeof e?.checkedAt ? e : null;
90
112
  } catch {
91
113
  return null;
92
114
  }
93
115
  }();
94
- if (t && e - t.checkedAt < 864e5) return {
95
- latest: t.latest,
96
- cacheStatus: "fresh"
97
- };
116
+ if (o && t - o.checkedAt < 864e5) return n(o.tags, "fresh");
98
117
  try {
99
- const t = await fetch("https://registry.npmjs.org/sheetxl/latest", {
100
- headers: { Accept: "application/vnd.npm.install-v1+json" },
101
- signal: AbortSignal.timeout(1500)
102
- });
103
- if (!t.ok) throw new Error(String(t.status));
104
- const n = (await t.json()).version;
105
- if (!n) throw new Error("no version");
118
+ const e = await fetch("https://registry.npmjs.org/-/package/@sheetxl%2fsdk/dist-tags", { signal: AbortSignal.timeout(1500) });
119
+ if (!e.ok) throw new Error(String(e.status));
120
+ const o = await e.json();
121
+ if ("string" != typeof o?.latest) throw new Error("no latest tag");
106
122
  return await async function(e) {
107
123
  try {
108
- await a(s.dirname(S()), { recursive: !0 }), await d(S(), JSON.stringify(e), "utf-8");
124
+ await l(s.dirname(A()), { recursive: !0 }), await p(A(), JSON.stringify(e), "utf-8");
109
125
  } catch {}
110
126
  }({
111
- checkedAt: e,
112
- latest: n
113
- }), {
114
- latest: n,
115
- cacheStatus: "refreshed"
116
- };
127
+ checkedAt: t,
128
+ tags: o
129
+ }), n(o, "refreshed");
117
130
  } catch {
118
- return t ? {
119
- latest: t.latest,
120
- cacheStatus: "fresh"
121
- } : {
131
+ return o ? n(o.tags, "fresh") : {
122
132
  latest: null,
133
+ tag: null,
123
134
  cacheStatus: "missing"
124
135
  };
125
136
  }
126
137
  }
127
- function T(e, t) {
128
- const n = (e) => e.split("-")[0].split(".").map((e) => Number.parseInt(e, 10) || 0), s = n(e), o = n(t);
129
- for (let e = 0; e < Math.max(s.length, o.length); e++) {
130
- const t = (s[e] ?? 0) - (o[e] ?? 0);
138
+ function N(e, t) {
139
+ const n = (e) => {
140
+ const t = e.indexOf("-"), n = t < 0 ? e : e.slice(0, t), s = t < 0 ? [] : e.slice(t + 1).split(".");
141
+ return [n.split(".").map((e) => Number.parseInt(e, 10) || 0), s];
142
+ }, [s, o] = n(e), [r, i] = n(t);
143
+ for (let e = 0; e < Math.max(s.length, r.length); e++) {
144
+ const t = (s[e] ?? 0) - (r[e] ?? 0);
131
145
  if (0 !== t) return t;
132
146
  }
147
+ if (!o.length || !i.length) return i.length - o.length;
148
+ for (let e = 0; e < Math.max(o.length, i.length); e++) {
149
+ const t = o[e], n = i[e];
150
+ if (void 0 === t) return -1;
151
+ if (void 0 === n) return 1;
152
+ const s = /^\d+$/.test(t), r = /^\d+$/.test(n);
153
+ if (s && r) {
154
+ const e = Number(t) - Number(n);
155
+ if (0 !== e) return e;
156
+ } else {
157
+ if (s !== r) return s ? -1 : 1;
158
+ if (t !== n) return t < n ? -1 : 1;
159
+ }
160
+ }
133
161
  return 0;
134
162
  }
135
- var N = "claude mcp add sheetxl -- npx -y sheetxl mcp", O = "npx -y sheetxl setup", _ = () => n.homedir();
136
- async function C(e) {
163
+ var T = "claude mcp add sheetxl -- npx -y @sheetxl/mcp", _ = {
164
+ command: "npx",
165
+ args: ["-y", "@sheetxl/mcp"]
166
+ }, P = "npx -y sheetxl setup agent", L = "npx -y skills add sheetxl/skills -g --all", E = "npx -y skills update", M = () => n.homedir();
167
+ function D(e) {
168
+ const t = s.resolve(e).replace(/\\/g, "/").replace(/\/+$/, "");
169
+ return "win32" === process.platform || "darwin" === process.platform ? t.toLowerCase() : t;
170
+ }
171
+ async function I(e) {
137
172
  const t = [];
138
173
  return await Promise.all(function(e) {
139
- const t = process.env.APPDATA, n = "win32" === process.platform ? t ? s.join(t, "Claude", "claude_desktop_config.json") : null : "darwin" === process.platform ? s.join(_(), "Library", "Application Support", "Claude", "claude_desktop_config.json") : s.join(_(), ".config", "Claude", "claude_desktop_config.json");
174
+ const t = process.env.APPDATA, n = "win32" === process.platform ? t ? s.join(t, "Claude", "claude_desktop_config.json") : null : "darwin" === process.platform ? s.join(M(), "Library", "Application Support", "Claude", "claude_desktop_config.json") : s.join(M(), ".config", "Claude", "claude_desktop_config.json");
140
175
  return [
141
176
  {
142
177
  name: "claude-code",
143
- file: s.join(_(), ".claude.json")
178
+ file: s.join(M(), ".claude.json")
179
+ },
180
+ {
181
+ name: "claude-code (plugin)",
182
+ file: s.join(M(), ".claude", "settings.json")
144
183
  },
145
184
  {
146
185
  name: "claude-code (project)",
@@ -152,7 +191,7 @@ async function C(e) {
152
191
  },
153
192
  {
154
193
  name: "cursor",
155
- file: s.join(_(), ".cursor", "mcp.json")
194
+ file: s.join(M(), ".cursor", "mcp.json")
156
195
  },
157
196
  {
158
197
  name: "cursor (project)",
@@ -160,7 +199,7 @@ async function C(e) {
160
199
  },
161
200
  {
162
201
  name: "windsurf",
163
- file: s.join(_(), ".codeium", "windsurf", "mcp_config.json")
202
+ file: s.join(M(), ".codeium", "windsurf", "mcp_config.json")
164
203
  },
165
204
  {
166
205
  name: "vscode (project)",
@@ -168,20 +207,22 @@ async function C(e) {
168
207
  },
169
208
  {
170
209
  name: "codex",
171
- file: s.join(_(), ".codex", "config.toml")
210
+ file: s.join(M(), ".codex", "config.toml")
172
211
  }
173
212
  ];
174
- }(e).map(async ({ name: e, file: n }) => {
175
- if (n) try {
176
- (function(e, t) {
213
+ }(e).map(async ({ name: n, file: s }) => {
214
+ if (s) try {
215
+ (function(e, t, n) {
177
216
  if (t.endsWith(".toml")) return /sheetxl/i.test(e);
178
217
  try {
179
- const t = JSON.parse(e), n = [
218
+ const t = JSON.parse(e), s = D(n), o = [
180
219
  t.mcpServers,
181
220
  t.servers,
182
- ...Object.values(t.projects ?? {}).map((e) => e?.mcpServers)
221
+ t.enabledPlugins,
222
+ ...Object.entries(t.projects ?? {}).filter(([e]) => D(e) === s).map(([, e]) => e?.mcpServers)
183
223
  ];
184
- for (const e of n) if (e && "object" == typeof e) for (const [t, n] of Object.entries(e)) {
224
+ for (const e of o) if (e && "object" == typeof e) for (const [t, n] of Object.entries(e)) {
225
+ if (!1 === n) continue;
185
226
  if (/sheetxl/i.test(t)) return !0;
186
227
  const e = JSON.stringify(n ?? "");
187
228
  if (/sheetxl/i.test(e)) return !0;
@@ -190,31 +231,81 @@ async function C(e) {
190
231
  } catch {
191
232
  return /sheetxl/i.test(e);
192
233
  }
193
- })(await l(n, "utf-8"), n) && t.push({
194
- name: e,
195
- file: n
234
+ })(await c(s, "utf-8"), s, e) && t.push({
235
+ name: n,
236
+ file: s
196
237
  });
197
238
  } catch {}
198
239
  })), t.sort((e, t) => e.name.localeCompare(t.name));
199
240
  }
200
- var P = e(import.meta.url);
201
- function E(e) {
241
+ var B = "sheetxl.sheetxl-vscode";
242
+ function J(e = "code") {
243
+ return `${e} --install-extension ${B} --pre-release`;
244
+ }
245
+ var W = [
246
+ ".vscode",
247
+ ".vscode-insiders",
248
+ ".vscode-server"
249
+ ], H = ["code", "code-insiders"];
250
+ function V(e, t) {
251
+ for (const n of t) for (const t of e) try {
252
+ if (o(s.join(n, t))) return s.join(n, t);
253
+ } catch {}
254
+ return null;
255
+ }
256
+ function X(e) {
257
+ let t;
258
+ try {
259
+ t = i(s.join(e, "extensions"));
260
+ } catch {
261
+ return null;
262
+ }
263
+ let n = null;
264
+ const o = `${B}-`;
265
+ for (const e of t) {
266
+ if (!e.toLowerCase().startsWith(o)) continue;
267
+ const t = e.slice(o.length).match(/^\d+\.\d+\.\d+/)?.[0];
268
+ t && (!n || N(t, n) > 0) && (n = t);
269
+ }
270
+ return n;
271
+ }
272
+ function U(e = {}) {
273
+ const t = e.home ?? n.homedir(), r = e.platform ?? process.platform, i = e.pathDirs ?? (process.env.PATH ?? "").split(s.delimiter).filter(Boolean);
274
+ let a = null;
275
+ for (const e of H) if (V("win32" === r ? [`${e}.cmd`, e] : [e], i)) {
276
+ a = e;
277
+ break;
278
+ }
279
+ const l = W.map((e) => s.join(t, e)).filter((e) => o(e));
280
+ if (!a && !l.length) return null;
281
+ let c = null;
282
+ for (const e of l) {
283
+ const t = X(e);
284
+ t && (!c || N(t, c) > 0) && (c = t);
285
+ }
286
+ return {
287
+ launcher: a,
288
+ extension: c
289
+ };
290
+ }
291
+ var K = e(import.meta.url);
292
+ function R(e) {
202
293
  try {
203
- return s.dirname(P.resolve(`${e}/package.json`));
294
+ return s.dirname(K.resolve(`${e}/package.json`));
204
295
  } catch {}
205
296
  for (const t of function(e) {
206
297
  const t = [];
207
298
  try {
208
- t.push(p(import.meta.resolve(e)));
299
+ t.push(f(import.meta.resolve(e)));
209
300
  } catch {}
210
301
  try {
211
- t.push(P.resolve(e));
302
+ t.push(K.resolve(e));
212
303
  } catch {}
213
304
  return t;
214
305
  }(e)) {
215
306
  let n = s.dirname(t);
216
307
  for (let t = 0; t < 8; t++) {
217
- if (L(n) === e) return n;
308
+ if (Y(n) === e) return n;
218
309
  const t = s.dirname(n);
219
310
  if (t === n) break;
220
311
  n = t;
@@ -222,67 +313,67 @@ function E(e) {
222
313
  }
223
314
  return null;
224
315
  }
225
- function L(e) {
316
+ function Y(e) {
226
317
  try {
227
318
  return JSON.parse(r(s.join(e, "package.json"), "utf-8")).name ?? null;
228
319
  } catch {
229
320
  return null;
230
321
  }
231
322
  }
232
- function B(e) {
323
+ function q(e) {
233
324
  return {
234
325
  version: e.getBuildVersion() || "local",
235
326
  build: e.getBuildDate() || null
236
327
  };
237
328
  }
238
- async function D(e) {
239
- const { surface: t, offline: i = !1, includeHost: a = !1, serverCount: c } = e, u = e.workspace ?? process.env.SHEETXL_WORKSPACE ?? process.cwd(), h = e.license(), d = h.then((e) => i || "local" === B(e).version ? null : A()), [p, f, m, v] = await Promise.all([
329
+ async function z(e) {
330
+ const { surface: t, offline: i = !1, includeHost: a = !1, serverCount: l } = e, u = e.workspace ?? process.env.SHEETXL_WORKSPACE ?? process.cwd(), h = e.license(), d = h.then((e) => i || "local" === q(e).version ? null : C(q(e).version)), [p, m, g, v] = await Promise.all([
240
331
  h,
241
- M(e, i),
332
+ F(e, i),
242
333
  d,
243
- C(u)
244
- ]), g = B(p), k = function(e, t) {
245
- const n = e.getExceptions(), s = e.isEval() ? "evaluation" : (e.getType() || "unlicensed").toLowerCase(), o = e.getExpiration(), r = o && !Number.isNaN(o.getTime()) ? o : null, i = null !== r && r.getTime() - Date.now() < 2592e6, a = r ? `expire${r.getTime() < Date.now() ? "d" : "s"} ${r.toISOString().slice(0, 10)}` : void 0;
246
- let l;
247
- if (t) {
248
- const t = e.getKeyFrom(), n = !t || /^no key$/i.test(t) ? "local" : t, s = e.getCpuCount(), o = e.getMemory();
249
- l = [`key: ${n}`, 0 === s && 0 === o ? "unmetered" : [s ? `${s} cores` : null, o ? `${o} GB` : null].filter(Boolean).join(" · ")].filter(Boolean).join(" · ");
250
- }
334
+ I(u)
335
+ ]), w = q(p), x = function(e, t) {
251
336
  return {
252
337
  name: "license",
253
- level: n.length || i ? "warn" : "ok",
254
- value: s,
255
- detail: n.length ? n.join("; ") : [i || t ? a : void 0, l].filter(Boolean).join(" — "),
256
- fix: n.length ? "sheetxl license activate <key>" : void 0
338
+ ...e.getSummary(t)
257
339
  };
258
- }(p, a), $ = [], x = "local" === g.version;
340
+ }(p, a), $ = [], j = "local" === w.version;
259
341
  $.push({
260
342
  name: "engine",
261
343
  level: "ok",
262
- value: `@sheetxl/sdk ${y(g.version, g.build)}`,
263
- detail: x ? "workspace build — unpublished" : g.build ? `built ${w(g.build)}` : void 0
344
+ value: `@sheetxl/sdk ${k(w.version, w.build)}`,
345
+ detail: j ? "workspace build — unpublished" : w.build ? `built ${y(w.build)}` : void 0
264
346
  });
265
- const j = Number.parseInt(process.version.slice(1), 10);
347
+ const b = Number.parseInt(process.version.slice(1), 10);
266
348
  $.push({
267
349
  name: "node",
268
- level: j < 24 ? "error" : "ok",
350
+ level: b < 24 ? "error" : "ok",
269
351
  value: process.version,
270
- detail: j < 24 ? "minimum is v24" : void 0,
271
- fix: j < 24 ? "install Node.js v24 or newer" : void 0
352
+ detail: b < 24 ? "minimum is v24" : void 0,
353
+ fix: b < 24 ? "install Node.js v24 or newer" : void 0
272
354
  });
273
- const b = function() {
274
- const e = E("@sheetxl/sdk");
275
- if (!e) return {
355
+ const S = function() {
356
+ let e = s.dirname(f(import.meta.url));
357
+ for (let t = 0; t < 2; t++) {
358
+ const t = s.join(e, "types", "scripting.d.ts");
359
+ if (o(t)) return {
360
+ path: t,
361
+ exists: !0
362
+ };
363
+ e = s.dirname(e);
364
+ }
365
+ const t = R("@sheetxl/sdk");
366
+ if (!t) return {
276
367
  path: null,
277
368
  exists: !1
278
369
  };
279
370
  try {
280
- const t = JSON.parse(r(s.join(e, "package.json"), "utf-8")), n = t.exports?.["."]?.types ?? t.types;
371
+ const e = JSON.parse(r(s.join(t, "package.json"), "utf-8")), n = e.exports?.["."]?.types ?? e.types;
281
372
  if (!n) return {
282
373
  path: null,
283
374
  exists: !1
284
375
  };
285
- const i = s.resolve(e, n), a = s.join(s.dirname(i), "scripting.d.ts");
376
+ const i = s.resolve(t, n), a = s.join(s.dirname(i), "scripting.d.ts");
286
377
  return o(a) ? {
287
378
  path: a,
288
379
  exists: !0
@@ -297,24 +388,24 @@ async function D(e) {
297
388
  };
298
389
  }
299
390
  }();
300
- $.push(b.exists ? {
391
+ $.push(S.exists ? {
301
392
  name: "types",
302
393
  level: "ok",
303
- value: b.path,
394
+ value: S.path,
304
395
  detail: `\`${e.apiCommand ?? ("mcp" === t ? "api" : "sheetxl api")} <Type>\` lists what a type can do without reading this`
305
396
  } : {
306
397
  name: "types",
307
398
  level: "warn",
308
- value: b.path ?? "not resolved",
309
- detail: b.path ? "declared but not present — the engine build may be incomplete" : "@sheetxl/sdk is not reachable from here",
310
- fix: O
399
+ value: S.path ?? "not resolved",
400
+ detail: S.path ? "declared but not present — the engine build may be incomplete" : "@sheetxl/sdk is not reachable from here",
401
+ fix: P
311
402
  });
312
- const S = await async function(e, t) {
403
+ const A = await async function(e, t) {
313
404
  const r = await async function(e) {
314
- const t = E(e);
405
+ const t = R(e);
315
406
  if (!t) return null;
316
407
  try {
317
- return JSON.parse(await l(s.join(t, "package.json"), "utf-8")).version ?? null;
408
+ return JSON.parse(await c(s.join(t, "package.json"), "utf-8")).version ?? null;
318
409
  } catch {
319
410
  return null;
320
411
  }
@@ -323,8 +414,8 @@ async function D(e) {
323
414
  const i = "mcp" === e ? "load with the `skill` prompt or the `sheetxl://skills/*` resources" : "read with `sheetxl skills`", a = function(e) {
324
415
  const t = n.homedir();
325
416
  return [
326
- s.join(t, ".claude", "skills", "sheetxl"),
327
417
  s.join(e, ".claude", "skills", "sheetxl"),
418
+ s.join(t, ".claude", "skills", "sheetxl"),
328
419
  s.join(t, ".config", "skills", "sheetxl"),
329
420
  s.join(t, ".skills", "sheetxl"),
330
421
  s.join(t, ".codex", "skills", "sheetxl"),
@@ -334,18 +425,18 @@ async function D(e) {
334
425
  if ("0.0.0" === r) return {
335
426
  name: "skills",
336
427
  level: "ok",
337
- value: E("@sheetxl/skills") ?? "@sheetxl/skills (workspace)",
338
- detail: [`workspace copy — SKILL.md and references/ — ${i}`, a ? `ignore the installed copy at ${a}` : null].filter(Boolean).join("; ")
428
+ value: R("@sheetxl/skills") ?? "@sheetxl/skills (workspace)",
429
+ detail: [`workspace copy — SKILL.md and references/ — ${i}`, a ? `read this copy first: it tracks the engine you are running; the installed copy at ${a} tracks a release and is the fallback` : null].filter(Boolean).join("; ")
339
430
  };
340
431
  if (!a) return {
341
432
  name: "skills",
342
433
  level: "ok",
343
434
  value: `@sheetxl/skills ${r}`,
344
- detail: `version-matched to this ${"mcp" === e ? "server" : "install"} — ${i}`
435
+ detail: `version-matched to this ${"mcp" === e ? "server" : "install"} — ${i}` + ("cli" === e ? `; no copy found in your agent's skill directories — \`${L}\` installs one` : "")
345
436
  };
346
- const c = await async function(e) {
437
+ const l = await async function(e) {
347
438
  try {
348
- const t = await l(s.join(e, "SKILL.md"), "utf-8");
439
+ const t = await c(s.join(e, "SKILL.md"), "utf-8");
349
440
  if (!t.startsWith("---")) return null;
350
441
  const n = t.indexOf("\n---", 3);
351
442
  if (-1 === n) return null;
@@ -357,34 +448,30 @@ async function D(e) {
357
448
  return null;
358
449
  }
359
450
  }(a);
360
- if (!c) return {
451
+ if (!l) return {
361
452
  name: "skills",
362
453
  level: "ok",
363
454
  value: `@sheetxl/skills ${r}`,
364
455
  detail: `installed at ${a} (version not stamped)`
365
456
  };
366
- const u = T(r, c) > 0;
457
+ const u = N(r, l) > 0;
367
458
  return {
368
459
  name: "skills",
369
460
  level: u ? "warn" : "ok",
370
461
  value: `@sheetxl/skills ${r}`,
371
- detail: u ? `installed copy is ${c} — stale; prefer this ${"mcp" === e ? "server" : "install"}'s: ${i}` : "current",
372
- ...u && "cli" === e ? { fix: "sheetxl skills" } : {}
462
+ detail: u ? `installed copy is ${l} — stale; prefer this ${"mcp" === e ? "server" : "install"}'s: ${i}` : "current",
463
+ ...u && "cli" === e ? { fix: E } : {}
373
464
  };
374
465
  }(t, u);
375
- S && $.push(S);
376
- const N = f.some((e) => e.hasView ?? "attended" === e.kind);
377
- return "mcp" === t ? $.push(function(e) {
466
+ A && $.push(A);
467
+ const O = m.some((e) => e.hasView ?? "attended" === e.kind);
468
+ "mcp" === t ? $.push(function(e) {
378
469
  const t = function(e) {
379
- const t = "win32" === process.platform ? [
470
+ return V("win32" === process.platform ? [
380
471
  "sheetxl.cmd",
381
472
  "sheetxl.exe",
382
473
  "sheetxl"
383
- ] : ["sheetxl"], n = [s.join(e, "node_modules", ".bin"), ...(process.env.PATH ?? "").split(s.delimiter).filter(Boolean)];
384
- for (const e of n) for (const n of t) try {
385
- if (o(s.join(e, n))) return s.join(e, n);
386
- } catch {}
387
- return null;
474
+ ] : ["sheetxl"], [s.join(e, "node_modules", ".bin"), ...(process.env.PATH ?? "").split(s.delimiter).filter(Boolean)]);
388
475
  }(e), n = "same engine, one dialect — for terminal-shaped work (`--json` piping, stdin, scripts); sessions stay here";
389
476
  return t ? {
390
477
  name: "cli",
@@ -397,69 +484,93 @@ async function D(e) {
397
484
  value: "not found on PATH",
398
485
  detail: `if you can run commands, \`npx -y sheetxl\` runs it anywhere Node does — ${n}`
399
486
  };
400
- }(u)) : E("@sheetxl/mcp") && $.push(function(e, t) {
401
- return e.length ? {
487
+ }(u)) : $.push(function(e, t) {
488
+ if (!e.length) return {
489
+ name: "mcp",
490
+ level: "warn",
491
+ value: "server available — no client registration found here",
492
+ detail: t ? "a client UI has a workbook open (see sessions), but no config here gives this agent the MCP tools — register to act on it (sessions, undo, in-grid highlights, prompts)" : "the server runs through npx (`npx -y @sheetxl/mcp`); until a client registers it, sessions, undo, in-grid highlights and prompts are unavailable",
493
+ fix: "sheetxl setup agent"
494
+ };
495
+ const n = `registered (${e.map((e) => e.name).join(", ")})`, s = e.filter((e) => e.name.startsWith("claude-code"));
496
+ return s.length > 1 ? {
497
+ name: "mcp",
498
+ level: "warn",
499
+ value: n,
500
+ detail: `Claude Code has SheetXL registered ${s.length} times (${s.map((e) => e.file).join(", ")}) and will launch a server for each — keep one. With the plugin enabled, the VS Code extension removes its own \`.mcp.json\` entry.`
501
+ } : {
402
502
  name: "mcp",
403
503
  level: "ok",
404
- value: `registered (${e.map((e) => e.name).join(", ")})`,
504
+ value: n,
405
505
  detail: "not connected from the CLI — a registered server attaches at the client's next session"
506
+ };
507
+ }(v, O));
508
+ const T = O ? null : function() {
509
+ const e = U();
510
+ if (!e) return null;
511
+ const t = "a live grid beside the agent, with in-grid highlights and questions";
512
+ return e.extension ? {
513
+ name: "vscode",
514
+ level: "ok",
515
+ value: `SheetXL extension ${e.extension} installed`,
516
+ detail: `${e.launcher ? `\`${e.launcher} book.xlsx\`` : "opening a workbook in VS Code"} gives the person ${t}`
406
517
  } : {
407
- name: "mcp",
408
- level: "warn",
409
- value: "server available — no client registration found here",
410
- detail: t ? "a client UI has a workbook open (see sessions), but no config here gives this agent the MCP tools — register to act on it (sessions, undo, in-grid highlights, prompts)" : "the server ships with this install (`sheetxl mcp`); until a client registers it, sessions, undo, in-grid highlights and prompts are unavailable",
411
- fix: "sheetxl setup"
518
+ name: "vscode",
519
+ level: "ok",
520
+ value: "available — SheetXL extension not installed",
521
+ detail: `optional: the extension gives the person ${t}. Offer it, do not install it unasked — ` + (e.launcher ? `\`${J(e.launcher)}\`` : "search \"SheetXL\" in the Extensions view")
412
522
  };
413
- }(v, N)), void 0 !== c && c > 1 && $.push({
523
+ }();
524
+ return T && $.push(T), void 0 !== l && l > 1 && $.push({
414
525
  name: "instances",
415
526
  level: "warn",
416
- value: `${c} servers running for this workspace`,
417
- detail: "sandbox sessions are per-process and are not shared between them — a session_id created through one is unusable through another; usually a duplicate MCP registration",
527
+ value: `${l} servers launched by this MCP client for this workspace`,
528
+ detail: "a duplicate MCP registration — sandbox sessions are per-process and are not shared between them, so a session_id created through one is unusable through another",
418
529
  fix: "remove the duplicate sheetxl entry from one of the MCP client configs"
419
- }), $.push(k), $.push({
530
+ }), $.push(x), $.push({
420
531
  name: "workspace",
421
532
  level: "ok",
422
533
  value: u,
423
534
  detail: "relative paths resolve here"
424
- }), x ? $.push({
535
+ }), j ? $.push({
425
536
  name: "update",
426
537
  level: "ok",
427
538
  value: "not applicable — local build",
428
539
  detail: "no published channel to update from; rebuild the workspace to pick up changes"
429
- }) : m && $.push(function(e, t) {
540
+ }) : g && $.push(function(e, t, n) {
430
541
  if (!t.latest) return {
431
542
  name: "update",
432
543
  level: "ok",
433
544
  value: "unknown",
434
545
  detail: "registry not reachable"
435
546
  };
436
- const n = T(t.latest, e) > 0;
547
+ const s = N(t.latest, e) > 0;
437
548
  return {
438
549
  name: "update",
439
- level: n ? "warn" : "ok",
440
- value: n ? `${t.latest} available` : "current",
441
- detail: n ? `running ${e}` : void 0,
442
- fix: n ? "npm install -g sheetxl@latest" : void 0
550
+ level: s ? "warn" : "ok",
551
+ value: s ? `${t.latest} available` : "current",
552
+ detail: s ? "mcp" === n ? `running ${e} — the MCP client's config decides which server runs (the VS Code extension updates itself)` : `running ${e}` : void 0,
553
+ fix: s ? "mcp" === n ? `npx -y @sheetxl/mcp@${t.tag}` : `npm install -g sheetxl@${t.tag}` : void 0
443
554
  };
444
- }(g.version, m)), {
555
+ }(w.version, g, t)), {
445
556
  product: "SheetXL",
446
- version: g.version,
447
- build: g.build,
557
+ version: w.version,
558
+ build: w.build,
448
559
  surface: t,
449
560
  collectedAt: (/* @__PURE__ */ new Date()).toISOString(),
450
561
  ok: !$.some((e) => "error" === e.level),
451
- attended: N,
452
- sessions: f,
562
+ attended: O,
563
+ sessions: m,
453
564
  checks: $,
454
- host: a ? I() : void 0
565
+ host: a ? G() : void 0
455
566
  };
456
567
  }
457
- async function M(e, t) {
568
+ async function F(e, t) {
458
569
  if (e.sessions) return [...await e.sessions()];
459
570
  if (t) return [];
460
571
  try {
461
- const e = await j();
462
- return e ? (await b(e)).map((e) => ({
572
+ const e = await b();
573
+ return e ? (await S(e)).map((e) => ({
463
574
  id: e.id,
464
575
  name: e.name,
465
576
  kind: "attended",
@@ -472,7 +583,7 @@ async function M(e, t) {
472
583
  return [];
473
584
  }
474
585
  }
475
- function I() {
586
+ function G() {
476
587
  const e = n.cpus(), t = process.memoryUsage(), o = n.totalmem();
477
588
  return {
478
589
  platform: n.platform(),
@@ -490,37 +601,37 @@ function I() {
490
601
  configStore: s.join(n.homedir(), ".config", "configstore", "sheetxl.json")
491
602
  };
492
603
  }
493
- var J = {
604
+ var Q = {
494
605
  ok: " ",
495
606
  warn: "!",
496
607
  error: "✗"
497
- }, H = (e, n) => "error" === e ? t.red(n) : "warn" === e ? t.yellow(n) : t.white(n);
498
- function W(e) {
608
+ }, Z = (e, n) => "error" === e ? t.red(n) : "warn" === e ? t.yellow(n) : t.white(n);
609
+ function ee(e) {
499
610
  const t = e.ok ? "engine ready" : "not ready", n = e.attended ? "attended" : "unattended";
500
- return `${e.product} — ${t} · ${n} · as of ${U(e.collectedAt)}`;
611
+ return `${e.product} — ${t} · ${n} · as of ${te(e.collectedAt)}`;
501
612
  }
502
- function U(e) {
613
+ function te(e) {
503
614
  const t = new Date(e);
504
615
  return Number.isNaN(t.getTime()) ? "unknown" : t.toTimeString().slice(0, 8);
505
616
  }
506
- function K(e) {
617
+ function ne(e) {
507
618
  const n = e.checks, s = Math.max(...n.map((e) => e.name.length)) + 2, o = " ".repeat(s + 4), r = [];
508
- r.push(e.ok ? t.cyanBright(W(e)) : t.yellow(W(e))), r.push("");
619
+ r.push(e.ok ? t.cyanBright(ee(e)) : t.yellow(ee(e))), r.push("");
509
620
  for (const e of n) {
510
- const n = "ok" === e.level ? " " : H(e.level, J[e.level]), i = t.dim(e.name.padEnd(s)), a = e.detail && e.detail.length <= 44 ? ` ${t.dim(`· ${e.detail}`)}` : "";
511
- r.push(` ${n} ${i}${H(e.level, e.value)}${a}`), e.detail && !a && r.push(`${o}${t.dim(e.detail)}`), e.fix && r.push(`${o}${t.yellow("→ ")}${t.yellow(e.fix)}`);
621
+ const n = "ok" === e.level ? " " : Z(e.level, Q[e.level]), i = t.dim(e.name.padEnd(s)), a = e.detail && e.detail.length <= 44 ? ` ${t.dim(`· ${e.detail}`)}` : "";
622
+ r.push(` ${n} ${i}${Z(e.level, e.value)}${a}`), e.detail && !a && r.push(`${o}${t.dim(e.detail)}`), e.fix && r.push(`${o}${t.yellow("→ ")}${t.yellow(e.fix)}`);
512
623
  }
513
624
  return r.join("\n");
514
625
  }
515
- function V(e) {
626
+ function se(e) {
516
627
  const t = [];
517
- t.push(`**${W(e)}**`), t.push("");
628
+ t.push(`**${ee(e)}**`), t.push("");
518
629
  for (const n of e.checks) {
519
630
  const e = "ok" === n.level ? "" : "warn" === n.level ? "⚠ " : "✗ ", s = n.detail ? ` — ${n.detail}` : "";
520
631
  t.push(`- ${e}**${n.name}**: ${n.value}${s}`);
521
632
  }
522
633
  if (t.push(""), t.push(function(e) {
523
- return e.attended ? "mcp" === e.surface ? "**Attended.** A human has that workbook open. When they are vague — \"fix this\", \"B10 looks wrong\" — they probably mean the workbook in front of them. Reach it through its session, never through the file on disk: what is on disk is stale the moment they have unsaved edits, and writing over it destroys their work with no undo. The session is yours to use — every `run` is one undoable commit — along with `highlight` marks and in-grid `prompt`s." : "**Attended.** A human has that workbook open, and there is no session to reach from the CLI — `--in` opens the file, which is the one thing you must not write back. This is a *read* surface: query, calculate, report what you found, and let them make the change or hand the work to the MCP server." : "**Unattended.** Nobody is watching. The files are yours to open, change and save directly, and nobody will catch a mistake for you — so verify your own work: read back what you wrote, recount what you fixed.";
634
+ return e.attended ? "mcp" === e.surface ? "**Attended.** A human has that workbook open and sees every change the moment it lands. When they are vague — \"fix this\", \"B10 looks wrong\" — they probably mean the workbook in front of them. Reach it through its session, never through the file on disk: what is on disk is stale the moment they have unsaved edits, and the session is where their undo lives. The session is yours to use: each `run` is one commit the user can step through and revert from the agent panel at the top right of their grid, so make the change, say what you changed, and `highlight` where — nothing about it needs a warning. In-grid `prompt`s are yours too." : "**Attended.** A human has that workbook open, and there is no session to reach from the CLI — `--in` opens the file, which is the one thing you must not write back. This is a *read* surface: query, calculate, report what you found, and let them make the change or hand the work to the MCP server." : "**Unattended.** Nobody is watching. The files are yours to open, change and save directly, and nobody will catch a mistake for you — so verify your own work: read back what you wrote, recount what you fixed.";
524
635
  }(e)), e.sessions.length) {
525
636
  t.push(""), t.push("**Sessions**"), t.push("");
526
637
  for (const n of e.sessions) {
@@ -528,7 +639,7 @@ function V(e) {
528
639
  n.kind,
529
640
  void 0 === n.hasView ? null : n.hasView ? "view" : "headless",
530
641
  n.active ? "active" : null
531
- ].filter(Boolean).join(", "), s = n.path ? ` path: \`${n.path}\`` : "", o = void 0 !== n.openedAt ? ` open since ${U(new Date(n.openedAt).toISOString())}` : "";
642
+ ].filter(Boolean).join(", "), s = n.path ? ` path: \`${n.path}\`` : "", o = void 0 !== n.openedAt ? ` open since ${te(new Date(n.openedAt).toISOString())}` : "";
532
643
  t.push(`- **${n.name}** id: \`${n.id}\` (${e})${s}${o}`);
533
644
  }
534
645
  }
@@ -539,63 +650,58 @@ function V(e) {
539
650
  }
540
651
  return t.join("\n");
541
652
  }
542
- var X = "SHEETXL_TOOL_LOG", F = /* @__PURE__ */ new Set([
653
+ var oe = "SHEETXL_TOOL_LOG", re = /* @__PURE__ */ new Set([
543
654
  "code",
544
655
  "source",
545
656
  "script",
546
657
  "argv"
547
- ]), R = /(^|[._-])(key|token|secret|password|credential)s?($|[._-])|licen[cs]e/i, Y = null, z = null, G = Promise.resolve(), q = {}, Q = null;
548
- function Z(e) {
658
+ ]), ie = /(^|[._-])(key|token|secret|password|credential)s?($|[._-])|licen[cs]e/i, ae = null, le = null, ce = Promise.resolve(), ue = {}, he = null;
659
+ function de(e) {
549
660
  const t = function() {
550
- const e = process.env[X];
661
+ const e = process.env[oe];
551
662
  if (void 0 === e) return null;
552
663
  const t = e.trim();
553
664
  return "" === t || /^(0|false|no|off)$/i.test(t) ? null : /^(1|true|yes|on)$/i.test(t) ? s.join(n.homedir(), ".sheetxl", "logs") : s.resolve(t);
554
665
  }();
555
- if (!t) return Y = null, null;
666
+ if (!t) return ae = null, null;
556
667
  const o = /* @__PURE__ */ new Date(), r = `${o.getFullYear()}${String(o.getMonth() + 1).padStart(2, "0")}${String(o.getDate()).padStart(2, "0")}`, i = e.tag ? `${r}-${e.tag}-${process.pid}.jsonl` : `${r}-${process.pid}.jsonl`;
557
- return Y = s.join(t, i), q = { transport: e.transport }, Y;
668
+ return ae = s.join(t, i), ue = { transport: e.transport }, ae;
558
669
  }
559
- function ee() {
560
- return Y;
670
+ function pe() {
671
+ return ae;
561
672
  }
562
- function te() {
563
- return null !== Y;
673
+ function fe() {
674
+ return null !== ae;
564
675
  }
565
- function ne(e) {
566
- q = {
567
- ...q,
676
+ function me(e) {
677
+ ue = {
678
+ ...ue,
568
679
  ...e
569
680
  };
570
681
  }
571
- function se(e) {
572
- Q = e;
682
+ function ge(e) {
683
+ he = e;
573
684
  }
574
- function oe(e, t) {
685
+ function ve(e, t) {
575
686
  return e.length <= t ? e : e.slice(0, t) + "…[truncated]";
576
687
  }
577
- function re(e, t) {
578
- if (R.test(e)) return "[redacted]";
579
- const n = F.has(e) ? 16384 : 2048;
580
- return "string" == typeof t ? oe(t, n) : Array.isArray(t) ? t.map((t) => re(e, t)) : t && "object" == typeof t ? Object.fromEntries(Object.entries(t).filter(([, e]) => void 0 !== e).map(([t, n]) => [t, re(F.has(e) ? e : t, n)])) : t;
688
+ function we(e, t) {
689
+ if (ie.test(e)) return "[redacted]";
690
+ const n = re.has(e) ? 16384 : 2048;
691
+ return "string" == typeof t ? ve(t, n) : Array.isArray(t) ? t.map((t) => we(e, t)) : t && "object" == typeof t ? Object.fromEntries(Object.entries(t).filter(([, e]) => void 0 !== e).map(([t, n]) => [t, we(re.has(e) ? e : t, n)])) : t;
581
692
  }
582
- function ie(e) {
583
- return null == e ? e : re("", e);
693
+ function ye(e) {
694
+ return null == e ? e : we("", e);
584
695
  }
585
- function ae(e) {
586
- return oe(e, 2048);
696
+ function ke(e) {
697
+ return ve(e, 2048);
587
698
  }
588
- function le(e) {
589
- const t = Y;
590
- if (!t && !Q) return;
591
- const n = {
592
- ts: (/* @__PURE__ */ new Date()).toISOString(),
593
- pid: process.pid,
594
- ...q,
595
- ...e
596
- };
597
- if (Q) try {
598
- Q(n);
699
+ function xe(e) {
700
+ const t = ae;
701
+ if (!t && !he) return;
702
+ const n = $e(e);
703
+ if (he) try {
704
+ he(n);
599
705
  } catch {}
600
706
  if (!t) return;
601
707
  let o;
@@ -606,16 +712,24 @@ function le(e) {
606
712
  _dropped: !0,
607
713
  _bytes: o.length
608
714
  },
609
- resultPreview: n.resultPreview ? oe(n.resultPreview, 1024) : void 0
715
+ resultPreview: n.resultPreview ? ve(n.resultPreview, 1024) : void 0
610
716
  }));
611
717
  } catch {
612
718
  return;
613
719
  }
614
- G = G.then(async () => {
615
- z || (z = a(s.dirname(t), { recursive: !0 }).then(() => {})), await z, await i(t, o + "\n", "utf-8");
720
+ ce = ce.then(async () => {
721
+ le || (le = l(s.dirname(t), { recursive: !0 }).then(() => {})), await le, await a(t, o + "\n", "utf-8");
616
722
  }).catch(() => {});
617
723
  }
618
- function ce() {
619
- return G;
724
+ function $e(e) {
725
+ return {
726
+ ts: (/* @__PURE__ */ new Date()).toISOString(),
727
+ pid: process.pid,
728
+ ...ue,
729
+ ...e
730
+ };
731
+ }
732
+ function je() {
733
+ return ce;
620
734
  }
621
- export { N as CLAUDE_CODE_FIX, O as GENERIC_FIX, X as TOOL_LOG_ENV, ie as capArgs, ae as capPreview, A as checkForUpdate, D as collectInfo, T as compareVersions, j as discoverRelay, b as fetchRelayWorkbooks, C as findMcpRegistrations, ce as flushToolLog, w as formatBuildInstant, y as formatBuildLabel, ee as getToolLogPath, Z as initToolLog, te as isToolLogEnabled, le as logToolCall, v as printMarkdown, K as renderInfo, V as renderInfoMarkdown, ne as setToolLogContext, se as setToolLogMirror, g as styleMarkdown };
735
+ export { T as CLAUDE_CODE_FIX, P as GENERIC_FIX, _ as MCP_LAUNCH, L as SKILLS_INSTALL, E as SKILLS_UPDATE, oe as TOOL_LOG_ENV, B as VSCODE_EXTENSION_ID, ye as capArgs, ke as capPreview, C as checkForUpdate, z as collectInfo, N as compareVersions, b as discoverRelay, $e as enrichToolLogRecord, S as fetchRelayWorkbooks, I as findMcpRegistrations, V as findOnPath, U as findVsCode, je as flushToolLog, y as formatBuildInstant, k as formatBuildLabel, pe as getToolLogPath, de as initToolLog, fe as isToolLogEnabled, xe as logToolCall, O as pickUpdate, v as printMarkdown, ne as renderInfo, se as renderInfoMarkdown, me as setToolLogContext, ge as setToolLogMirror, w as styleMarkdown, J as vscodeExtensionInstall };
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@sheetxl/utils-node",
3
3
  "description": "SheetXL - Node-only utilities: terminal presentation, environment reporting, tool logging",
4
- "version": "0.8.0-beta.9",
5
- "license": "SEE LICENSE IN <LICENSE>",
4
+ "version": "1.0.2",
5
+ "license": "MIT",
6
6
  "type": "module",
7
7
  "exports": {
8
8
  ".": {
@@ -37,9 +37,9 @@
37
37
  "cli"
38
38
  ],
39
39
  "dependencies": {
40
- "chalk": "^5.6.2"
40
+ "chalk": "^6.0.1"
41
41
  },
42
42
  "devDependencies": {
43
- "@types/node": "^26.1.2"
43
+ "@types/node": "^26.6.6"
44
44
  }
45
45
  }
@@ -55,6 +55,8 @@ export declare namespace Info {
55
55
  | 'mcp'
56
56
  /** MCP surface only — whether the same engine is reachable as a command on this machine. */
57
57
  | 'cli'
58
+ /** Only when VS Code is found and no workbook is open in it — whether the SheetXL extension is installed. */
59
+ | 'vscode'
58
60
  /** MCP surface only, and only when there is more than one — see {@link CollectOptions.instances}. */
59
61
  | 'instances' | 'license' | 'workspace' | 'update';
60
62
  /**
@@ -151,23 +153,21 @@ export declare namespace Info {
151
153
  * satisfies this without either side knowing about the other — `LicenseManager.getDetails()`
152
154
  * is what both surfaces actually pass.
153
155
  *
154
- * Only what a report reads is listed. Entitlements the report never prints (domains,
155
- * developer seats, per-feature validity) stay the engine's business.
156
+ * Only what a report reads is listed — the build's identity, and the license row the engine
157
+ * composes itself. What a license means (editions, exceptions, the evaluation's dates, the fix)
158
+ * is the engine's business; this package only lays the row out.
156
159
  */
157
160
  interface LicenseSource {
158
161
  /** The engine build this license was issued against, and when it was built. */
159
162
  getBuildVersion(): string;
160
163
  getBuildDate(): string;
161
- getType(): string;
162
- isEval(): boolean;
163
- getExpiration(): Date | null;
164
- /** Anything the agent can act on — an unlicensed feature, a violated term. */
165
- getExceptions(): string[];
166
- /** Where the key came from (`envVar`, `configStore`, …). Host diagnostics only. */
167
- getKeyFrom(): string;
168
- /** Entitlement ceilings, in their stated units (memory is GB). Zero means unmetered. */
169
- getCpuCount(): number;
170
- getMemory(): number;
164
+ /** The license as a report row; `includeHost` adds the key's source and capacity. */
165
+ getSummary(includeHost?: boolean): {
166
+ level: 'ok' | 'warn';
167
+ value: string;
168
+ detail?: string;
169
+ fix?: string;
170
+ };
171
171
  }
172
172
  /** How much the caller is willing to pay for, and what it can answer that the report cannot. */
173
173
  interface CollectOptions {
@@ -191,13 +191,14 @@ export declare namespace Info {
191
191
  */
192
192
  readonly sessions?: () => Promise<readonly Session[]>;
193
193
  /**
194
- * How many servers are serving this workspace, when the caller is one of them.
194
+ * How many servers the caller's own MCP client launched for this workspace, counting the caller.
195
195
  *
196
196
  * @remarks
197
197
  * Passed in rather than probed, for the same reason as `sessions`: only a running server knows
198
- * this, and only about its own kind. Reported ONLY when there is more than one — "1 server is
199
- * running" is not something an agent can act on, whereas two means their session ids are split
200
- * between processes and a create/run pair can straddle them.
198
+ * this, and only about its own kind. Servers launched by OTHER client sessions are not counted —
199
+ * each answers only its own agent. Reported ONLY when there is more than one: that is a duplicate
200
+ * registration, whose session ids are split between processes so a create/run pair can straddle
201
+ * them.
201
202
  */
202
203
  readonly serverCount?: number;
203
204
  /** Skip every network and localhost probe. Nothing is guessed — unreachable checks are omitted. */
@@ -5,4 +5,5 @@ export * from './renderInfo';
5
5
  export * from './relay';
6
6
  export * from './updateCheck';
7
7
  export * from './mcpClients';
8
+ export * from './vscodeClient';
8
9
  //# sourceMappingURL=index.d.ts.map
@@ -10,8 +10,17 @@ export interface McpRegistration {
10
10
  * telling an agent to "add it to the config" invites it to invent a schema. So the generic fix
11
11
  * points at the one-command setup path instead of a file to hand-edit.
12
12
  */
13
- export declare const CLAUDE_CODE_FIX = "claude mcp add sheetxl -- npx -y sheetxl mcp";
14
- export declare const GENERIC_FIX = "npx -y sheetxl setup";
13
+ export declare const CLAUDE_CODE_FIX = "claude mcp add sheetxl -- npx -y @sheetxl/mcp";
14
+ /** The launch line every other client's config carries. */
15
+ export declare const MCP_LAUNCH: {
16
+ readonly command: "npx";
17
+ readonly args: readonly ["-y", "@sheetxl/mcp"];
18
+ };
19
+ export declare const GENERIC_FIX = "npx -y sheetxl setup agent";
20
+ /** Installs the agent skill from the public `sheetxl/skills` repo into every agent it finds. */
21
+ export declare const SKILLS_INSTALL = "npx -y skills add sheetxl/skills -g --all";
22
+ /** Refreshes a copy installed that way. */
23
+ export declare const SKILLS_UPDATE = "npx -y skills update";
15
24
  /** Every client config found on this machine that registers the SheetXL MCP server. */
16
25
  export declare function findMcpRegistrations(workspace: string): Promise<McpRegistration[]>;
17
26
  //# sourceMappingURL=mcpClients.d.ts.map
@@ -7,24 +7,38 @@
7
7
  * goes unnoticed for months.
8
8
  */
9
9
  export interface UpdateStatus {
10
+ /** The newest version on the running build's channel, or `null` when unknown. */
10
11
  readonly latest: string | null;
12
+ /** The dist-tag that installs {@link latest}. */
13
+ readonly tag: string | null;
11
14
  readonly cacheStatus: 'fresh' | 'refreshed' | 'missing';
12
15
  }
13
16
  /**
14
- * The latest published `sheetxl` version, from cache when fresh.
17
+ * The newest release a `current` build should move to.
15
18
  *
19
+ * @remarks
20
+ * A stable build follows `latest`. A prerelease follows `beta` — `latest` stays on the last
21
+ * stable release for the whole beta — but still hears about a stable release that overtakes it.
22
+ */
23
+ export declare function pickUpdate(current: string, tags: Readonly<Record<string, string>>): {
24
+ latest: string;
25
+ tag: string;
26
+ } | null;
27
+ /**
28
+ * The newest published SheetXL on `current`'s channel, from cache when fresh.
29
+ *
30
+ * @param current The running engine version; its prerelease tail picks the channel.
16
31
  * @param now Injected so the TTL is testable without a clock.
17
32
  */
18
- export declare function checkForUpdate(now?: number): Promise<UpdateStatus>;
33
+ export declare function checkForUpdate(current: string, now?: number): Promise<UpdateStatus>;
19
34
  /**
20
- * Compares two dot-separated versions, ignoring any prerelease tail.
35
+ * Compares two versions with semver precedence.
21
36
  *
22
37
  * @returns positive when `a` is newer than `b`.
23
38
  *
24
39
  * @remarks
25
- * Not a semver dependency for one comparison. Prerelease ordering is out of scope: a
26
- * prerelease and its release compare equal, which errs toward *not* nagging someone who
27
- * deliberately installed a `-next` build.
40
+ * Not a semver dependency for one comparison. A prerelease sorts before its release, and
41
+ * prerelease identifiers compare numerically when both are numbers (`beta.10` after `beta.9`).
28
42
  */
29
43
  export declare function compareVersions(a: string, b: string): number;
30
44
  //# sourceMappingURL=updateCheck.d.ts.map
@@ -0,0 +1,32 @@
1
+ /**
2
+ * Whether VS Code is on this machine, and whether the SheetXL extension is installed in it.
3
+ *
4
+ * @remarks
5
+ * The extension is the one surface that puts a person in the grid beside the agent, and nothing
6
+ * else in the report can see it until a workbook is already open there. This looks for the editor
7
+ * itself, so an agent can offer the extension to someone who has VS Code and has never heard of it.
8
+ *
9
+ * Local file reads only, and best-effort in both directions: a portable install with no launcher
10
+ * on PATH and no profile directory reports as absent, and an extension uninstalled since the
11
+ * editor last restarted still has its directory and reports as installed.
12
+ */
13
+ export declare const VSCODE_EXTENSION_ID = "sheetxl.sheetxl-vscode";
14
+ /** The command that installs the extension, spelled for the launcher that was found. */
15
+ export declare function vscodeExtensionInstall(launcher?: string): string;
16
+ export interface VsCodeInstall {
17
+ /** The launcher as it is typed (`code`, `code-insiders`), or `null` when none is on PATH. */
18
+ readonly launcher: string | null;
19
+ /** The installed SheetXL extension's version, or `null` when it is not installed. */
20
+ readonly extension: string | null;
21
+ }
22
+ /** Where to look. Defaults to this machine; given explicitly by tests. */
23
+ export interface VsCodeProbe {
24
+ readonly home?: string;
25
+ readonly pathDirs?: readonly string[];
26
+ readonly platform?: NodeJS.Platform;
27
+ }
28
+ /** The first of `names` present in `dirs`, as a full path. Unreadable entries are skipped. */
29
+ export declare function findOnPath(names: readonly string[], dirs: readonly string[]): string | null;
30
+ /** VS Code as found on this machine, or `null` when there is no sign of it. */
31
+ export declare function findVsCode(probe?: VsCodeProbe): VsCodeInstall | null;
32
+ //# sourceMappingURL=vscodeClient.d.ts.map
@@ -4,7 +4,7 @@
4
4
  * @remarks
5
5
  * Every call an agent makes against SheetXL (MCP tool, CLI command) is recorded here, including
6
6
  * the **full `run` source**, which every other surface discards. Two things need it: reviewing a
7
- * manual VS Code/Copilot/CLI session after the fact, and the running log file a SpreadsheetBench
7
+ * manual VS Code/Copilot/CLI session after the fact, and the running log file a benchmark
8
8
  * submission has to ship.
9
9
  *
10
10
  * It lives in `@sheetxl/utils-node` rather than in the MCP server for the same reason relay discovery
@@ -36,7 +36,11 @@ export interface ToolLogRecord {
36
36
  clientName?: string | null;
37
37
  clientVersion?: string | null;
38
38
  args?: unknown;
39
- status?: 'ok' | 'error';
39
+ /**
40
+ * `crashed`: the process died while the call ran, so it never answered. Written by the process
41
+ * that replaced it, from the record the call left when it started.
42
+ */
43
+ status?: 'ok' | 'error' | 'crashed';
40
44
  error?: string | null;
41
45
  durationMs?: number;
42
46
  resultBytes?: number;
@@ -99,6 +103,13 @@ export declare function capPreview(text: string): string;
99
103
  * into the tool call being logged.
100
104
  */
101
105
  export declare function logToolCall(record: ToolLogRecord): void;
106
+ /**
107
+ * `record` as {@link logToolCall} writes it: stamped with the time, the process and the context
108
+ * every record from this process carries. For a surface that keeps a record of its own before the
109
+ * call has an outcome — the MCP server's in-flight marker — so the line it may later stand in for
110
+ * reads like every other.
111
+ */
112
+ export declare function enrichToolLogRecord(record: ToolLogRecord): ToolLogRecord;
102
113
  /** Flushes pending appends. For process-exit paths that want the last line on disk. */
103
114
  export declare function flushToolLog(): Promise<void>;
104
115
  //# sourceMappingURL=toolLog.d.ts.map