@sheetxl/utils-node 0.8.0-beta.20 → 0.8.0-beta.21

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.
@@ -1,5 +1,5 @@
1
1
  /**
2
- * @license @sheetxl/utils-node - SheetXL - Node-only utilities: terminal presentation, environment reporting, tool logging - v0.8.0-beta.20
2
+ * @license @sheetxl/utils-node - SheetXL - Node-only utilities: terminal presentation, environment reporting, tool logging - v0.8.0-beta.21
3
3
  *
4
4
  * (C) 2026-present SheetXL Inc. & Michael T. Ford
5
5
  * License: MIT
@@ -8,32 +8,32 @@ 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 r, readFileSync as o } 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), g = (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(v(e.endsWith("\n") ? e : e + "\n", n));
18
- }, v = (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");
29
- async function x(e) {
28
+ var x = () => s.join(n.homedir(), ".sheetxl", "locks");
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 $(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,46 +43,46 @@ async function $(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`);
50
- })(), t = await x(e);
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
+ })(), t = await $(e);
51
51
  if (t) {
52
- if (await $(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 x(t);
69
+ const t = s.join(x(), e), n = await $(t);
70
70
  if (n) {
71
- if (await $(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
- function A(e, t) {
84
+ var A = () => s.join(n.homedir(), ".sheetxl", "cache", "update.json");
85
+ function O(e, t) {
86
86
  const n = e.includes("-") ? ["beta", "latest"] : ["latest"];
87
87
  let s = null;
88
88
  for (const e of n) {
@@ -94,9 +94,9 @@ function A(e, t) {
94
94
  }
95
95
  return s;
96
96
  }
97
- async function O(e, t = Date.now()) {
97
+ async function C(e, t = Date.now()) {
98
98
  const n = (t, n) => {
99
- const s = A(e, t);
99
+ const s = O(e, t);
100
100
  return s ? {
101
101
  ...s,
102
102
  cacheStatus: n
@@ -105,30 +105,30 @@ async function O(e, t = Date.now()) {
105
105
  tag: null,
106
106
  cacheStatus: "missing"
107
107
  };
108
- }, r = await async function() {
108
+ }, o = await async function() {
109
109
  try {
110
- const e = JSON.parse(await l(S(), "utf-8"));
110
+ const e = JSON.parse(await c(A(), "utf-8"));
111
111
  return "object" == typeof e?.tags && e.tags && "number" == typeof e?.checkedAt ? e : null;
112
112
  } catch {
113
113
  return null;
114
114
  }
115
115
  }();
116
- if (r && t - r.checkedAt < 864e5) return n(r.tags, "fresh");
116
+ if (o && t - o.checkedAt < 864e5) return n(o.tags, "fresh");
117
117
  try {
118
118
  const e = await fetch("https://registry.npmjs.org/-/package/@sheetxl%2fsdk/dist-tags", { signal: AbortSignal.timeout(1500) });
119
119
  if (!e.ok) throw new Error(String(e.status));
120
- const r = await e.json();
121
- if ("string" != typeof r?.latest) throw new Error("no latest tag");
120
+ const o = await e.json();
121
+ if ("string" != typeof o?.latest) throw new Error("no latest tag");
122
122
  return await async function(e) {
123
123
  try {
124
- 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");
125
125
  } catch {}
126
126
  }({
127
127
  checkedAt: t,
128
- tags: r
129
- }), n(r, "refreshed");
128
+ tags: o
129
+ }), n(o, "refreshed");
130
130
  } catch {
131
- return r ? n(r.tags, "fresh") : {
131
+ return o ? n(o.tags, "fresh") : {
132
132
  latest: null,
133
133
  tag: null,
134
134
  cacheStatus: "missing"
@@ -139,47 +139,47 @@ function N(e, t) {
139
139
  const n = (e) => {
140
140
  const t = e.indexOf("-"), n = t < 0 ? e : e.slice(0, t), s = t < 0 ? [] : e.slice(t + 1).split(".");
141
141
  return [n.split(".").map((e) => Number.parseInt(e, 10) || 0), s];
142
- }, [s, r] = n(e), [o, i] = n(t);
143
- for (let e = 0; e < Math.max(s.length, o.length); e++) {
144
- const t = (s[e] ?? 0) - (o[e] ?? 0);
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);
145
145
  if (0 !== t) return t;
146
146
  }
147
- if (!r.length || !i.length) return i.length - r.length;
148
- for (let e = 0; e < Math.max(r.length, i.length); e++) {
149
- const t = r[e], n = i[e];
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
150
  if (void 0 === t) return -1;
151
151
  if (void 0 === n) return 1;
152
- const s = /^\d+$/.test(t), o = /^\d+$/.test(n);
153
- if (s && o) {
152
+ const s = /^\d+$/.test(t), r = /^\d+$/.test(n);
153
+ if (s && r) {
154
154
  const e = Number(t) - Number(n);
155
155
  if (0 !== e) return e;
156
156
  } else {
157
- if (s !== o) return s ? -1 : 1;
157
+ if (s !== r) return s ? -1 : 1;
158
158
  if (t !== n) return t < n ? -1 : 1;
159
159
  }
160
160
  }
161
161
  return 0;
162
162
  }
163
- var C = "claude mcp add sheetxl -- npx -y @sheetxl/mcp", _ = {
163
+ var T = "claude mcp add sheetxl -- npx -y @sheetxl/mcp", _ = {
164
164
  command: "npx",
165
165
  args: ["-y", "@sheetxl/mcp"]
166
- }, T = "npx -y sheetxl setup agent", P = () => n.homedir();
167
- function L(e) {
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
168
  const t = s.resolve(e).replace(/\\/g, "/").replace(/\/+$/, "");
169
169
  return "win32" === process.platform || "darwin" === process.platform ? t.toLowerCase() : t;
170
170
  }
171
- async function M(e) {
171
+ async function I(e) {
172
172
  const t = [];
173
173
  return await Promise.all(function(e) {
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(P(), "Library", "Application Support", "Claude", "claude_desktop_config.json") : s.join(P(), ".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");
175
175
  return [
176
176
  {
177
177
  name: "claude-code",
178
- file: s.join(P(), ".claude.json")
178
+ file: s.join(M(), ".claude.json")
179
179
  },
180
180
  {
181
181
  name: "claude-code (plugin)",
182
- file: s.join(P(), ".claude", "settings.json")
182
+ file: s.join(M(), ".claude", "settings.json")
183
183
  },
184
184
  {
185
185
  name: "claude-code (project)",
@@ -191,7 +191,7 @@ async function M(e) {
191
191
  },
192
192
  {
193
193
  name: "cursor",
194
- file: s.join(P(), ".cursor", "mcp.json")
194
+ file: s.join(M(), ".cursor", "mcp.json")
195
195
  },
196
196
  {
197
197
  name: "cursor (project)",
@@ -199,7 +199,7 @@ async function M(e) {
199
199
  },
200
200
  {
201
201
  name: "windsurf",
202
- file: s.join(P(), ".codeium", "windsurf", "mcp_config.json")
202
+ file: s.join(M(), ".codeium", "windsurf", "mcp_config.json")
203
203
  },
204
204
  {
205
205
  name: "vscode (project)",
@@ -207,7 +207,7 @@ async function M(e) {
207
207
  },
208
208
  {
209
209
  name: "codex",
210
- file: s.join(P(), ".codex", "config.toml")
210
+ file: s.join(M(), ".codex", "config.toml")
211
211
  }
212
212
  ];
213
213
  }(e).map(async ({ name: n, file: s }) => {
@@ -215,13 +215,13 @@ async function M(e) {
215
215
  (function(e, t, n) {
216
216
  if (t.endsWith(".toml")) return /sheetxl/i.test(e);
217
217
  try {
218
- const t = JSON.parse(e), s = L(n), r = [
218
+ const t = JSON.parse(e), s = D(n), o = [
219
219
  t.mcpServers,
220
220
  t.servers,
221
221
  t.enabledPlugins,
222
- ...Object.entries(t.projects ?? {}).filter(([e]) => L(e) === s).map(([, e]) => e?.mcpServers)
222
+ ...Object.entries(t.projects ?? {}).filter(([e]) => D(e) === s).map(([, e]) => e?.mcpServers)
223
223
  ];
224
- for (const e of r) 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
225
  if (!1 === n) continue;
226
226
  if (/sheetxl/i.test(t)) return !0;
227
227
  const e = JSON.stringify(n ?? "");
@@ -231,31 +231,81 @@ async function M(e) {
231
231
  } catch {
232
232
  return /sheetxl/i.test(e);
233
233
  }
234
- })(await l(s, "utf-8"), s, e) && t.push({
234
+ })(await c(s, "utf-8"), s, e) && t.push({
235
235
  name: n,
236
236
  file: s
237
237
  });
238
238
  } catch {}
239
239
  })), t.sort((e, t) => e.name.localeCompare(t.name));
240
240
  }
241
- var E = e(import.meta.url);
242
- function D(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) {
243
293
  try {
244
- return s.dirname(E.resolve(`${e}/package.json`));
294
+ return s.dirname(K.resolve(`${e}/package.json`));
245
295
  } catch {}
246
296
  for (const t of function(e) {
247
297
  const t = [];
248
298
  try {
249
- t.push(p(import.meta.resolve(e)));
299
+ t.push(f(import.meta.resolve(e)));
250
300
  } catch {}
251
301
  try {
252
- t.push(E.resolve(e));
302
+ t.push(K.resolve(e));
253
303
  } catch {}
254
304
  return t;
255
305
  }(e)) {
256
306
  let n = s.dirname(t);
257
307
  for (let t = 0; t < 8; t++) {
258
- if (I(n) === e) return n;
308
+ if (Y(n) === e) return n;
259
309
  const t = s.dirname(n);
260
310
  if (t === n) break;
261
311
  n = t;
@@ -263,36 +313,36 @@ function D(e) {
263
313
  }
264
314
  return null;
265
315
  }
266
- function I(e) {
316
+ function Y(e) {
267
317
  try {
268
- return JSON.parse(o(s.join(e, "package.json"), "utf-8")).name ?? null;
318
+ return JSON.parse(r(s.join(e, "package.json"), "utf-8")).name ?? null;
269
319
  } catch {
270
320
  return null;
271
321
  }
272
322
  }
273
- function J(e) {
323
+ function q(e) {
274
324
  return {
275
325
  version: e.getBuildVersion() || "local",
276
326
  build: e.getBuildDate() || null
277
327
  };
278
328
  }
279
- async function B(e) {
280
- 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" === J(e).version ? null : O(J(e).version)), [f, m, g, 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([
281
331
  h,
282
- W(e, i),
332
+ F(e, i),
283
333
  d,
284
- M(u)
285
- ]), k = J(f), x = function(e, t) {
334
+ I(u)
335
+ ]), w = q(p), x = function(e, t) {
286
336
  return {
287
337
  name: "license",
288
338
  ...e.getSummary(t)
289
339
  };
290
- }(f, a), $ = [], j = "local" === k.version;
340
+ }(p, a), $ = [], j = "local" === w.version;
291
341
  $.push({
292
342
  name: "engine",
293
343
  level: "ok",
294
- value: `@sheetxl/sdk ${y(k.version, k.build)}`,
295
- detail: j ? "workspace build — unpublished" : k.build ? `built ${w(k.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
296
346
  });
297
347
  const b = Number.parseInt(process.version.slice(1), 10);
298
348
  $.push({
@@ -303,33 +353,33 @@ async function B(e) {
303
353
  fix: b < 24 ? "install Node.js v24 or newer" : void 0
304
354
  });
305
355
  const S = function() {
306
- let e = s.dirname(p(import.meta.url));
356
+ let e = s.dirname(f(import.meta.url));
307
357
  for (let t = 0; t < 2; t++) {
308
358
  const t = s.join(e, "types", "scripting.d.ts");
309
- if (r(t)) return {
359
+ if (o(t)) return {
310
360
  path: t,
311
361
  exists: !0
312
362
  };
313
363
  e = s.dirname(e);
314
364
  }
315
- const t = D("@sheetxl/sdk");
365
+ const t = R("@sheetxl/sdk");
316
366
  if (!t) return {
317
367
  path: null,
318
368
  exists: !1
319
369
  };
320
370
  try {
321
- const e = JSON.parse(o(s.join(t, "package.json"), "utf-8")), n = e.exports?.["."]?.types ?? e.types;
371
+ const e = JSON.parse(r(s.join(t, "package.json"), "utf-8")), n = e.exports?.["."]?.types ?? e.types;
322
372
  if (!n) return {
323
373
  path: null,
324
374
  exists: !1
325
375
  };
326
376
  const i = s.resolve(t, n), a = s.join(s.dirname(i), "scripting.d.ts");
327
- return r(a) ? {
377
+ return o(a) ? {
328
378
  path: a,
329
379
  exists: !0
330
380
  } : {
331
381
  path: i,
332
- exists: r(i)
382
+ exists: o(i)
333
383
  };
334
384
  } catch {
335
385
  return {
@@ -348,19 +398,19 @@ async function B(e) {
348
398
  level: "warn",
349
399
  value: S.path ?? "not resolved",
350
400
  detail: S.path ? "declared but not present — the engine build may be incomplete" : "@sheetxl/sdk is not reachable from here",
351
- fix: T
401
+ fix: P
352
402
  });
353
403
  const A = await async function(e, t) {
354
- const o = await async function(e) {
355
- const t = D(e);
404
+ const r = await async function(e) {
405
+ const t = R(e);
356
406
  if (!t) return null;
357
407
  try {
358
- 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;
359
409
  } catch {
360
410
  return null;
361
411
  }
362
412
  }("@sheetxl/skills");
363
- if (!o) return null;
413
+ if (!r) return null;
364
414
  const i = "mcp" === e ? "load with the `skill` prompt or the `sheetxl://skills/*` resources" : "read with `sheetxl skills`", a = function(e) {
365
415
  const t = n.homedir();
366
416
  return [
@@ -371,61 +421,57 @@ async function B(e) {
371
421
  s.join(t, ".codex", "skills", "sheetxl"),
372
422
  s.join(t, ".cursor", "skills", "sheetxl")
373
423
  ];
374
- }(t).find((e) => r(e));
375
- if ("0.0.0" === o) return {
424
+ }(t).find((e) => o(e));
425
+ if ("0.0.0" === r) return {
376
426
  name: "skills",
377
427
  level: "ok",
378
- value: D("@sheetxl/skills") ?? "@sheetxl/skills (workspace)",
428
+ value: R("@sheetxl/skills") ?? "@sheetxl/skills (workspace)",
379
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("; ")
380
430
  };
381
431
  if (!a) return {
382
432
  name: "skills",
383
433
  level: "ok",
384
- value: `@sheetxl/skills ${o}`,
385
- detail: `version-matched to this ${"mcp" === e ? "server" : "install"} — ${i}`
434
+ value: `@sheetxl/skills ${r}`,
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` : "")
386
436
  };
387
- const c = await async function(e) {
437
+ const l = await async function(e) {
388
438
  try {
389
- const t = await l(s.join(e, "SKILL.md"), "utf-8");
439
+ const t = await c(s.join(e, "SKILL.md"), "utf-8");
390
440
  if (!t.startsWith("---")) return null;
391
441
  const n = t.indexOf("\n---", 3);
392
442
  if (-1 === n) return null;
393
- const r = t.slice(3, n).match(/^version:\s*(.*)$/m);
394
- if (!r) return null;
395
- const o = r[1].trim().replace(/^["']|["']$/g, "");
396
- return o && "0.0.0" !== o ? o : null;
443
+ const o = t.slice(3, n).match(/^version:\s*(.*)$/m);
444
+ if (!o) return null;
445
+ const r = o[1].trim().replace(/^["']|["']$/g, "");
446
+ return r && "0.0.0" !== r ? r : null;
397
447
  } catch {
398
448
  return null;
399
449
  }
400
450
  }(a);
401
- if (!c) return {
451
+ if (!l) return {
402
452
  name: "skills",
403
453
  level: "ok",
404
- value: `@sheetxl/skills ${o}`,
454
+ value: `@sheetxl/skills ${r}`,
405
455
  detail: `installed at ${a} (version not stamped)`
406
456
  };
407
- const u = N(o, c) > 0;
457
+ const u = N(r, l) > 0;
408
458
  return {
409
459
  name: "skills",
410
460
  level: u ? "warn" : "ok",
411
- value: `@sheetxl/skills ${o}`,
412
- detail: u ? `installed copy is ${c} — stale; prefer this ${"mcp" === e ? "server" : "install"}'s: ${i}` : "current",
413
- ...u && "cli" === e ? { fix: "sheetxl skills" } : {}
461
+ value: `@sheetxl/skills ${r}`,
462
+ detail: u ? `installed copy is ${l} — stale; prefer this ${"mcp" === e ? "server" : "install"}'s: ${i}` : "current",
463
+ ...u && "cli" === e ? { fix: E } : {}
414
464
  };
415
465
  }(t, u);
416
466
  A && $.push(A);
417
- const C = m.some((e) => e.hasView ?? "attended" === e.kind);
418
- return "mcp" === t ? $.push(function(e) {
467
+ const O = m.some((e) => e.hasView ?? "attended" === e.kind);
468
+ "mcp" === t ? $.push(function(e) {
419
469
  const t = function(e) {
420
- const t = "win32" === process.platform ? [
470
+ return V("win32" === process.platform ? [
421
471
  "sheetxl.cmd",
422
472
  "sheetxl.exe",
423
473
  "sheetxl"
424
- ] : ["sheetxl"], n = [s.join(e, "node_modules", ".bin"), ...(process.env.PATH ?? "").split(s.delimiter).filter(Boolean)];
425
- for (const e of n) for (const n of t) try {
426
- if (r(s.join(e, n))) return s.join(e, n);
427
- } catch {}
428
- return null;
474
+ ] : ["sheetxl"], [s.join(e, "node_modules", ".bin"), ...(process.env.PATH ?? "").split(s.delimiter).filter(Boolean)]);
429
475
  }(e), n = "same engine, one dialect — for terminal-shaped work (`--json` piping, stdin, scripts); sessions stay here";
430
476
  return t ? {
431
477
  name: "cli",
@@ -458,10 +504,27 @@ async function B(e) {
458
504
  value: n,
459
505
  detail: "not connected from the CLI — a registered server attaches at the client's next session"
460
506
  };
461
- }(v, C)), void 0 !== c && c > 1 && $.push({
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}`
517
+ } : {
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")
522
+ };
523
+ }();
524
+ return T && $.push(T), void 0 !== l && l > 1 && $.push({
462
525
  name: "instances",
463
526
  level: "warn",
464
- value: `${c} servers launched by this MCP client for this workspace`,
527
+ value: `${l} servers launched by this MCP client for this workspace`,
465
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",
466
529
  fix: "remove the duplicate sheetxl entry from one of the MCP client configs"
467
530
  }), $.push(x), $.push({
@@ -489,25 +552,25 @@ async function B(e) {
489
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,
490
553
  fix: s ? "mcp" === n ? `npx -y @sheetxl/mcp@${t.tag}` : `npm install -g sheetxl@${t.tag}` : void 0
491
554
  };
492
- }(k.version, g, t)), {
555
+ }(w.version, g, t)), {
493
556
  product: "SheetXL",
494
- version: k.version,
495
- build: k.build,
557
+ version: w.version,
558
+ build: w.build,
496
559
  surface: t,
497
560
  collectedAt: (/* @__PURE__ */ new Date()).toISOString(),
498
561
  ok: !$.some((e) => "error" === e.level),
499
- attended: C,
562
+ attended: O,
500
563
  sessions: m,
501
564
  checks: $,
502
- host: a ? H() : void 0
565
+ host: a ? G() : void 0
503
566
  };
504
567
  }
505
- async function W(e, t) {
568
+ async function F(e, t) {
506
569
  if (e.sessions) return [...await e.sessions()];
507
570
  if (t) return [];
508
571
  try {
509
- const e = await j();
510
- return e ? (await b(e)).map((e) => ({
572
+ const e = await b();
573
+ return e ? (await S(e)).map((e) => ({
511
574
  id: e.id,
512
575
  name: e.name,
513
576
  kind: "attended",
@@ -520,8 +583,8 @@ async function W(e, t) {
520
583
  return [];
521
584
  }
522
585
  }
523
- function H() {
524
- const e = n.cpus(), t = process.memoryUsage(), r = n.totalmem();
586
+ function G() {
587
+ const e = n.cpus(), t = process.memoryUsage(), o = n.totalmem();
525
588
  return {
526
589
  platform: n.platform(),
527
590
  release: n.release(),
@@ -530,39 +593,39 @@ function H() {
530
593
  arch: process.arch,
531
594
  cpuCount: e.length,
532
595
  cpuModel: e[0]?.model?.trim() ?? "unknown",
533
- memoryTotal: r,
534
- memoryUsed: r - n.freemem(),
596
+ memoryTotal: o,
597
+ memoryUsed: o - n.freemem(),
535
598
  heapTotal: t.heapTotal,
536
599
  heapUsed: t.heapUsed,
537
600
  nodeEnv: "production",
538
601
  configStore: s.join(n.homedir(), ".config", "configstore", "sheetxl.json")
539
602
  };
540
603
  }
541
- var V = {
604
+ var Q = {
542
605
  ok: " ",
543
606
  warn: "!",
544
607
  error: "✗"
545
- }, U = (e, n) => "error" === e ? t.red(n) : "warn" === e ? t.yellow(n) : t.white(n);
546
- function X(e) {
608
+ }, Z = (e, n) => "error" === e ? t.red(n) : "warn" === e ? t.yellow(n) : t.white(n);
609
+ function ee(e) {
547
610
  const t = e.ok ? "engine ready" : "not ready", n = e.attended ? "attended" : "unattended";
548
- return `${e.product} — ${t} · ${n} · as of ${K(e.collectedAt)}`;
611
+ return `${e.product} — ${t} · ${n} · as of ${te(e.collectedAt)}`;
549
612
  }
550
- function K(e) {
613
+ function te(e) {
551
614
  const t = new Date(e);
552
615
  return Number.isNaN(t.getTime()) ? "unknown" : t.toTimeString().slice(0, 8);
553
616
  }
554
- function R(e) {
555
- const n = e.checks, s = Math.max(...n.map((e) => e.name.length)) + 2, r = " ".repeat(s + 4), o = [];
556
- o.push(e.ok ? t.cyanBright(X(e)) : t.yellow(X(e))), o.push("");
617
+ function ne(e) {
618
+ const n = e.checks, s = Math.max(...n.map((e) => e.name.length)) + 2, o = " ".repeat(s + 4), r = [];
619
+ r.push(e.ok ? t.cyanBright(ee(e)) : t.yellow(ee(e))), r.push("");
557
620
  for (const e of n) {
558
- const n = "ok" === e.level ? " " : U(e.level, V[e.level]), i = t.dim(e.name.padEnd(s)), a = e.detail && e.detail.length <= 44 ? ` ${t.dim(`· ${e.detail}`)}` : "";
559
- o.push(` ${n} ${i}${U(e.level, e.value)}${a}`), e.detail && !a && o.push(`${r}${t.dim(e.detail)}`), e.fix && o.push(`${r}${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)}`);
560
623
  }
561
- return o.join("\n");
624
+ return r.join("\n");
562
625
  }
563
- function Y(e) {
626
+ function se(e) {
564
627
  const t = [];
565
- t.push(`**${X(e)}**`), t.push("");
628
+ t.push(`**${ee(e)}**`), t.push("");
566
629
  for (const n of e.checks) {
567
630
  const e = "ok" === n.level ? "" : "warn" === n.level ? "⚠ " : "✗ ", s = n.detail ? ` — ${n.detail}` : "";
568
631
  t.push(`- ${e}**${n.name}**: ${n.value}${s}`);
@@ -576,8 +639,8 @@ function Y(e) {
576
639
  n.kind,
577
640
  void 0 === n.hasView ? null : n.hasView ? "view" : "headless",
578
641
  n.active ? "active" : null
579
- ].filter(Boolean).join(", "), s = n.path ? ` path: \`${n.path}\`` : "", r = void 0 !== n.openedAt ? ` open since ${K(new Date(n.openedAt).toISOString())}` : "";
580
- t.push(`- **${n.name}** id: \`${n.id}\` (${e})${s}${r}`);
642
+ ].filter(Boolean).join(", "), s = n.path ? ` path: \`${n.path}\`` : "", o = void 0 !== n.openedAt ? ` open since ${te(new Date(n.openedAt).toISOString())}` : "";
643
+ t.push(`- **${n.name}** id: \`${n.id}\` (${e})${s}${o}`);
581
644
  }
582
645
  }
583
646
  const n = e.checks.filter((e) => e.fix);
@@ -587,86 +650,86 @@ function Y(e) {
587
650
  }
588
651
  return t.join("\n");
589
652
  }
590
- var z = "SHEETXL_TOOL_LOG", F = /* @__PURE__ */ new Set([
653
+ var oe = "SHEETXL_TOOL_LOG", re = /* @__PURE__ */ new Set([
591
654
  "code",
592
655
  "source",
593
656
  "script",
594
657
  "argv"
595
- ]), q = /(^|[._-])(key|token|secret|password|credential)s?($|[._-])|licen[cs]e/i, G = null, Q = null, Z = Promise.resolve(), ee = {}, te = null;
596
- function ne(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) {
597
660
  const t = function() {
598
- const e = process.env[z];
661
+ const e = process.env[oe];
599
662
  if (void 0 === e) return null;
600
663
  const t = e.trim();
601
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);
602
665
  }();
603
- if (!t) return G = null, null;
604
- const r = /* @__PURE__ */ new Date(), o = `${r.getFullYear()}${String(r.getMonth() + 1).padStart(2, "0")}${String(r.getDate()).padStart(2, "0")}`, i = e.tag ? `${o}-${e.tag}-${process.pid}.jsonl` : `${o}-${process.pid}.jsonl`;
605
- return G = s.join(t, i), ee = { transport: e.transport }, G;
666
+ if (!t) return ae = null, null;
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`;
668
+ return ae = s.join(t, i), ue = { transport: e.transport }, ae;
606
669
  }
607
- function se() {
608
- return G;
670
+ function pe() {
671
+ return ae;
609
672
  }
610
- function re() {
611
- return null !== G;
673
+ function fe() {
674
+ return null !== ae;
612
675
  }
613
- function oe(e) {
614
- ee = {
615
- ...ee,
676
+ function me(e) {
677
+ ue = {
678
+ ...ue,
616
679
  ...e
617
680
  };
618
681
  }
619
- function ie(e) {
620
- te = e;
682
+ function ge(e) {
683
+ he = e;
621
684
  }
622
- function ae(e, t) {
685
+ function ve(e, t) {
623
686
  return e.length <= t ? e : e.slice(0, t) + "…[truncated]";
624
687
  }
625
- function le(e, t) {
626
- if (q.test(e)) return "[redacted]";
627
- const n = F.has(e) ? 16384 : 2048;
628
- return "string" == typeof t ? ae(t, n) : Array.isArray(t) ? t.map((t) => le(e, t)) : t && "object" == typeof t ? Object.fromEntries(Object.entries(t).filter(([, e]) => void 0 !== e).map(([t, n]) => [t, le(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;
629
692
  }
630
- function ce(e) {
631
- return null == e ? e : le("", e);
693
+ function ye(e) {
694
+ return null == e ? e : we("", e);
632
695
  }
633
- function ue(e) {
634
- return ae(e, 2048);
696
+ function ke(e) {
697
+ return ve(e, 2048);
635
698
  }
636
- function he(e) {
637
- const t = G;
638
- if (!t && !te) return;
639
- const n = de(e);
640
- if (te) try {
641
- te(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);
642
705
  } catch {}
643
706
  if (!t) return;
644
- let r;
707
+ let o;
645
708
  try {
646
- r = JSON.stringify(n), r.length > 65536 && (r = JSON.stringify({
709
+ o = JSON.stringify(n), o.length > 65536 && (o = JSON.stringify({
647
710
  ...n,
648
711
  args: {
649
712
  _dropped: !0,
650
- _bytes: r.length
713
+ _bytes: o.length
651
714
  },
652
- resultPreview: n.resultPreview ? ae(n.resultPreview, 1024) : void 0
715
+ resultPreview: n.resultPreview ? ve(n.resultPreview, 1024) : void 0
653
716
  }));
654
717
  } catch {
655
718
  return;
656
719
  }
657
- Z = Z.then(async () => {
658
- Q || (Q = a(s.dirname(t), { recursive: !0 }).then(() => {})), await Q, await i(t, r + "\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");
659
722
  }).catch(() => {});
660
723
  }
661
- function de(e) {
724
+ function $e(e) {
662
725
  return {
663
726
  ts: (/* @__PURE__ */ new Date()).toISOString(),
664
727
  pid: process.pid,
665
- ...ee,
728
+ ...ue,
666
729
  ...e
667
730
  };
668
731
  }
669
- function pe() {
670
- return Z;
732
+ function je() {
733
+ return ce;
671
734
  }
672
- export { C as CLAUDE_CODE_FIX, T as GENERIC_FIX, _ as MCP_LAUNCH, z as TOOL_LOG_ENV, ce as capArgs, ue as capPreview, O as checkForUpdate, B as collectInfo, N as compareVersions, j as discoverRelay, de as enrichToolLogRecord, b as fetchRelayWorkbooks, M as findMcpRegistrations, pe as flushToolLog, w as formatBuildInstant, y as formatBuildLabel, se as getToolLogPath, ne as initToolLog, re as isToolLogEnabled, he as logToolCall, A as pickUpdate, g as printMarkdown, R as renderInfo, Y as renderInfoMarkdown, oe as setToolLogContext, ie as setToolLogMirror, v 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,7 +1,7 @@
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.20",
4
+ "version": "0.8.0-beta.21",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "exports": {
@@ -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
  /**
@@ -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
@@ -17,6 +17,10 @@ export declare const MCP_LAUNCH: {
17
17
  readonly args: readonly ["-y", "@sheetxl/mcp"];
18
18
  };
19
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";
20
24
  /** Every client config found on this machine that registers the SheetXL MCP server. */
21
25
  export declare function findMcpRegistrations(workspace: string): Promise<McpRegistration[]>;
22
26
  //# sourceMappingURL=mcpClients.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