@sheetxl/utils-node 0.7.28-beta.4 → 0.8.0-beta.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.
@@ -1,5 +1,5 @@
1
1
  /**
2
- * @license @sheetxl/utils-node - SheetXL - Node-only utilities: terminal presentation, environment reporting, tool logging - v0.7.28-beta.4
2
+ * @license @sheetxl/utils-node - SheetXL - Node-only utilities: terminal presentation, environment reporting, tool logging - v0.8.0-beta.2
3
3
  *
4
4
  * (C) 2026-present SheetXL Inc. & Michael T. Ford
5
5
  * License: The license can be found at https://www.sheetxl.com/license.
@@ -13,17 +13,27 @@ import { appendFile as i, mkdir as a, readFile as l, readdir as c, stat as u, un
13
13
  import { fileURLToPath as p } from "node:url";
14
14
  import { createHash as f } from "node:crypto";
15
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) => {
16
- const n = t?.stream ?? process.stdout, s = e.endsWith("\n") ? e : e + "\n", o = n.isTTY ? s.split("\n").map(m).join("\n") : s;
17
- n.write(o);
18
- }, g = () => s.join(n.homedir(), ".sheetxl", "locks");
19
- async function w(e) {
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) {
20
+ const t = new Date(e);
21
+ if (Number.isNaN(t.getTime())) return e;
22
+ const n = (e) => String(e).padStart(2, "0");
23
+ return `${t.getFullYear()}-${n(t.getMonth() + 1)}-${n(t.getDate())} ${n(t.getHours())}:${n(t.getMinutes())}`;
24
+ }
25
+ function y(e, t) {
26
+ return e && "local" !== e ? e : t ? `local ${w(t)}` : "local";
27
+ }
28
+ var k = () => s.join(n.homedir(), ".sheetxl", "locks");
29
+ async function $(e) {
20
30
  try {
21
31
  return JSON.parse(await l(e, "utf-8"));
22
32
  } catch {
23
33
  return null;
24
34
  }
25
35
  }
26
- async function y(e) {
36
+ async function x(e) {
27
37
  try {
28
38
  return (await fetch(`http://127.0.0.1:${e.port}/sheetxl-mcp/ping`, {
29
39
  headers: { Authorization: `Bearer ${e.token}` },
@@ -33,49 +43,49 @@ async function y(e) {
33
43
  return !1;
34
44
  }
35
45
  }
36
- async function k() {
46
+ async function j() {
37
47
  const e = (() => {
38
48
  const e = process.env.SHEETXL_WORKSPACE ?? process.cwd(), t = f("sha256").update(e).digest("hex").slice(0, 8);
39
- return s.join(g(), `${t}.lock`);
40
- })(), t = await w(e);
49
+ return s.join(k(), `${t}.lock`);
50
+ })(), t = await $(e);
41
51
  if (t) {
42
- if (await y(t)) return t;
52
+ if (await x(t)) return t;
43
53
  await h(e).catch(() => {});
44
54
  }
45
55
  return async function() {
46
56
  let e;
47
57
  try {
48
- e = (await c(g())).filter((e) => e.endsWith(".lock"));
58
+ e = (await c(k())).filter((e) => e.endsWith(".lock"));
49
59
  } catch {
50
60
  return null;
51
61
  }
52
62
  if (!e.length) return null;
53
63
  const t = await Promise.all(e.map(async (e) => ({
54
64
  f: e,
55
- mtime: (await u(s.join(g(), e))).mtimeMs
65
+ mtime: (await u(s.join(k(), e))).mtimeMs
56
66
  })));
57
67
  t.sort((e, t) => t.mtime - e.mtime);
58
68
  for (const { f: e } of t) {
59
- const t = s.join(g(), e), n = await w(t);
69
+ const t = s.join(k(), e), n = await $(t);
60
70
  if (n) {
61
- if (await y(n)) return n;
71
+ if (await x(n)) return n;
62
72
  await h(t).catch(() => {});
63
73
  }
64
74
  }
65
75
  return null;
66
76
  }();
67
77
  }
68
- async function x(e) {
78
+ async function b(e) {
69
79
  return await (await fetch(`http://127.0.0.1:${e.port}/sheetxl-mcp/relay-workbooks`, {
70
80
  headers: { Authorization: `Bearer ${e.token}` },
71
81
  signal: AbortSignal.timeout(2e3)
72
82
  })).json();
73
83
  }
74
- var $ = () => s.join(n.homedir(), ".sheetxl", "cache", "update.json");
75
- async function j(e = Date.now()) {
84
+ var S = () => s.join(n.homedir(), ".sheetxl", "cache", "update.json");
85
+ async function A(e = Date.now()) {
76
86
  const t = await async function() {
77
87
  try {
78
- const e = JSON.parse(await l($(), "utf-8"));
88
+ const e = JSON.parse(await l(S(), "utf-8"));
79
89
  return "string" != typeof e?.latest || "number" != typeof e?.checkedAt ? null : e;
80
90
  } catch {
81
91
  return null;
@@ -95,7 +105,7 @@ async function j(e = Date.now()) {
95
105
  if (!n) throw new Error("no version");
96
106
  return await async function(e) {
97
107
  try {
98
- await a(s.dirname($()), { recursive: !0 }), await d($(), JSON.stringify(e), "utf-8");
108
+ await a(s.dirname(S()), { recursive: !0 }), await d(S(), JSON.stringify(e), "utf-8");
99
109
  } catch {}
100
110
  }({
101
111
  checkedAt: e,
@@ -114,7 +124,7 @@ async function j(e = Date.now()) {
114
124
  };
115
125
  }
116
126
  }
117
- function b(e, t) {
127
+ function T(e, t) {
118
128
  const n = (e) => e.split("-")[0].split(".").map((e) => Number.parseInt(e, 10) || 0), s = n(e), o = n(t);
119
129
  for (let e = 0; e < Math.max(s.length, o.length); e++) {
120
130
  const t = (s[e] ?? 0) - (o[e] ?? 0);
@@ -122,15 +132,15 @@ function b(e, t) {
122
132
  }
123
133
  return 0;
124
134
  }
125
- var S = "claude mcp add sheetxl -- npx -y sheetxl mcp", A = "npx -y sheetxl setup", O = () => n.homedir();
126
- async function T(e) {
135
+ var N = "claude mcp add sheetxl -- npx -y sheetxl mcp", O = "npx -y sheetxl setup", _ = () => n.homedir();
136
+ async function C(e) {
127
137
  const t = [];
128
138
  return await Promise.all(function(e) {
129
- const t = process.env.APPDATA, n = "win32" === process.platform ? t ? s.join(t, "Claude", "claude_desktop_config.json") : null : "darwin" === process.platform ? s.join(O(), "Library", "Application Support", "Claude", "claude_desktop_config.json") : s.join(O(), ".config", "Claude", "claude_desktop_config.json");
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");
130
140
  return [
131
141
  {
132
142
  name: "claude-code",
133
- file: s.join(O(), ".claude.json")
143
+ file: s.join(_(), ".claude.json")
134
144
  },
135
145
  {
136
146
  name: "claude-code (project)",
@@ -142,7 +152,7 @@ async function T(e) {
142
152
  },
143
153
  {
144
154
  name: "cursor",
145
- file: s.join(O(), ".cursor", "mcp.json")
155
+ file: s.join(_(), ".cursor", "mcp.json")
146
156
  },
147
157
  {
148
158
  name: "cursor (project)",
@@ -150,7 +160,7 @@ async function T(e) {
150
160
  },
151
161
  {
152
162
  name: "windsurf",
153
- file: s.join(O(), ".codeium", "windsurf", "mcp_config.json")
163
+ file: s.join(_(), ".codeium", "windsurf", "mcp_config.json")
154
164
  },
155
165
  {
156
166
  name: "vscode (project)",
@@ -158,7 +168,7 @@ async function T(e) {
158
168
  },
159
169
  {
160
170
  name: "codex",
161
- file: s.join(O(), ".codex", "config.toml")
171
+ file: s.join(_(), ".codex", "config.toml")
162
172
  }
163
173
  ];
164
174
  }(e).map(async ({ name: e, file: n }) => {
@@ -187,10 +197,10 @@ async function T(e) {
187
197
  } catch {}
188
198
  })), t.sort((e, t) => e.name.localeCompare(t.name));
189
199
  }
190
- var _ = e(import.meta.url);
191
- function N(e) {
200
+ var P = e(import.meta.url);
201
+ function E(e) {
192
202
  try {
193
- return s.dirname(_.resolve(`${e}/package.json`));
203
+ return s.dirname(P.resolve(`${e}/package.json`));
194
204
  } catch {}
195
205
  for (const t of function(e) {
196
206
  const t = [];
@@ -198,13 +208,13 @@ function N(e) {
198
208
  t.push(p(import.meta.resolve(e)));
199
209
  } catch {}
200
210
  try {
201
- t.push(_.resolve(e));
211
+ t.push(P.resolve(e));
202
212
  } catch {}
203
213
  return t;
204
214
  }(e)) {
205
215
  let n = s.dirname(t);
206
216
  for (let t = 0; t < 8; t++) {
207
- if (P(n) === e) return n;
217
+ if (L(n) === e) return n;
208
218
  const t = s.dirname(n);
209
219
  if (t === n) break;
210
220
  n = t;
@@ -212,25 +222,26 @@ function N(e) {
212
222
  }
213
223
  return null;
214
224
  }
215
- function P(e) {
225
+ function L(e) {
216
226
  try {
217
227
  return JSON.parse(r(s.join(e, "package.json"), "utf-8")).name ?? null;
218
228
  } catch {
219
229
  return null;
220
230
  }
221
231
  }
222
- async function C(e) {
223
- const { surface: t, offline: i = !1, includeHost: a = !1, serverCount: c } = e, u = e.workspace ?? process.env.SHEETXL_WORKSPACE ?? process.cwd(), [h, d, p, f] = await Promise.all([
224
- e.license(),
225
- E(e, i),
226
- i ? Promise.resolve(null) : j(),
227
- T(u)
228
- ]), m = function(e) {
229
- return {
230
- version: e.getBuildVersion() || "local",
231
- build: e.getBuildDate() || null
232
- };
233
- }(h), v = function(e, t) {
232
+ function B(e) {
233
+ return {
234
+ version: e.getBuildVersion() || "local",
235
+ build: e.getBuildDate() || null
236
+ };
237
+ }
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([
240
+ h,
241
+ M(e, i),
242
+ d,
243
+ C(u)
244
+ ]), g = B(p), k = function(e, t) {
234
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;
235
246
  let l;
236
247
  if (t) {
@@ -244,23 +255,23 @@ async function C(e) {
244
255
  detail: n.length ? n.join("; ") : [i || t ? a : void 0, l].filter(Boolean).join(" — "),
245
256
  fix: n.length ? "sheetxl license activate <key>" : void 0
246
257
  };
247
- }(h, a), g = [], w = "local" === m.version;
248
- g.push({
258
+ }(p, a), $ = [], x = "local" === g.version;
259
+ $.push({
249
260
  name: "engine",
250
261
  level: "ok",
251
- value: w ? "@sheetxl/sdk local workspace build" : `@sheetxl/sdk ${m.version}`,
252
- detail: m.build ? `built ${m.build}` : w ? "unpublished" : void 0
262
+ value: `@sheetxl/sdk ${y(g.version, g.build)}`,
263
+ detail: x ? "workspace build — unpublished" : g.build ? `built ${w(g.build)}` : void 0
253
264
  });
254
- const y = Number.parseInt(process.version.slice(1), 10);
255
- g.push({
265
+ const j = Number.parseInt(process.version.slice(1), 10);
266
+ $.push({
256
267
  name: "node",
257
- level: y < 24 ? "error" : "ok",
268
+ level: j < 24 ? "error" : "ok",
258
269
  value: process.version,
259
- detail: y < 24 ? "minimum is v24" : void 0,
260
- fix: y < 24 ? "install Node.js v24 or newer" : void 0
270
+ detail: j < 24 ? "minimum is v24" : void 0,
271
+ fix: j < 24 ? "install Node.js v24 or newer" : void 0
261
272
  });
262
- const k = function() {
263
- const e = N("@sheetxl/sdk");
273
+ const b = function() {
274
+ const e = E("@sheetxl/sdk");
264
275
  if (!e) return {
265
276
  path: null,
266
277
  exists: !1
@@ -271,8 +282,11 @@ async function C(e) {
271
282
  path: null,
272
283
  exists: !1
273
284
  };
274
- const i = s.resolve(e, n);
275
- return {
285
+ const i = s.resolve(e, n), a = s.join(s.dirname(i), "scripting.d.ts");
286
+ return o(a) ? {
287
+ path: a,
288
+ exists: !0
289
+ } : {
276
290
  path: i,
277
291
  exists: o(i)
278
292
  };
@@ -283,20 +297,21 @@ async function C(e) {
283
297
  };
284
298
  }
285
299
  }();
286
- g.push(k.exists ? {
300
+ $.push(b.exists ? {
287
301
  name: "types",
288
302
  level: "ok",
289
- value: k.path
303
+ value: b.path,
304
+ detail: `\`${e.apiCommand ?? ("mcp" === t ? "api" : "sheetxl api")} <Type>\` lists what a type can do without reading this`
290
305
  } : {
291
306
  name: "types",
292
307
  level: "warn",
293
- value: k.path ?? "not resolved",
294
- detail: k.path ? "declared but not present — the engine build may be incomplete" : "@sheetxl/sdk is not reachable from here",
295
- fix: A
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
296
311
  });
297
- const x = await async function(e, t) {
312
+ const S = await async function(e, t) {
298
313
  const r = await async function(e) {
299
- const t = N(e);
314
+ const t = E(e);
300
315
  if (!t) return null;
301
316
  try {
302
317
  return JSON.parse(await l(s.join(t, "package.json"), "utf-8")).version ?? null;
@@ -316,6 +331,12 @@ async function C(e) {
316
331
  s.join(t, ".cursor", "skills", "sheetxl")
317
332
  ];
318
333
  }(t).find((e) => o(e));
334
+ if ("0.0.0" === r) return {
335
+ name: "skills",
336
+ 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("; ")
339
+ };
319
340
  if (!a) return {
320
341
  name: "skills",
321
342
  level: "ok",
@@ -342,7 +363,7 @@ async function C(e) {
342
363
  value: `@sheetxl/skills ${r}`,
343
364
  detail: `installed at ${a} (version not stamped)`
344
365
  };
345
- const u = b(r, c) > 0;
366
+ const u = T(r, c) > 0;
346
367
  return {
347
368
  name: "skills",
348
369
  level: u ? "warn" : "ok",
@@ -351,9 +372,9 @@ async function C(e) {
351
372
  ...u && "cli" === e ? { fix: "sheetxl skills" } : {}
352
373
  };
353
374
  }(t, u);
354
- x && g.push(x);
355
- const $ = d.some((e) => e.hasView ?? "attended" === e.kind);
356
- return "mcp" === t ? g.push(function(e) {
375
+ S && $.push(S);
376
+ const N = f.some((e) => e.hasView ?? "attended" === e.kind);
377
+ return "mcp" === t ? $.push(function(e) {
357
378
  const t = function(e) {
358
379
  const t = "win32" === process.platform ? [
359
380
  "sheetxl.cmd",
@@ -376,7 +397,7 @@ async function C(e) {
376
397
  value: "not found on PATH",
377
398
  detail: `if you can run commands, \`npx -y sheetxl\` runs it anywhere Node does — ${n}`
378
399
  };
379
- }(u)) : N("@sheetxl/mcp") && g.push(function(e, t) {
400
+ }(u)) : E("@sheetxl/mcp") && $.push(function(e, t) {
380
401
  return e.length ? {
381
402
  name: "mcp",
382
403
  level: "ok",
@@ -389,31 +410,30 @@ async function C(e) {
389
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",
390
411
  fix: "sheetxl setup"
391
412
  };
392
- }(f, $)), void 0 !== c && c > 1 && g.push({
413
+ }(v, N)), void 0 !== c && c > 1 && $.push({
393
414
  name: "instances",
394
415
  level: "warn",
395
416
  value: `${c} servers running for this workspace`,
396
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",
397
418
  fix: "remove the duplicate sheetxl entry from one of the MCP client configs"
398
- }), g.push(v), g.push({
419
+ }), $.push(k), $.push({
399
420
  name: "workspace",
400
421
  level: "ok",
401
422
  value: u,
402
423
  detail: "relative paths resolve here"
403
- }), p && g.push(function(e, t) {
424
+ }), x ? $.push({
425
+ name: "update",
426
+ level: "ok",
427
+ value: "not applicable — local build",
428
+ detail: "no published channel to update from; rebuild the workspace to pick up changes"
429
+ }) : m && $.push(function(e, t) {
404
430
  if (!t.latest) return {
405
431
  name: "update",
406
432
  level: "ok",
407
433
  value: "unknown",
408
434
  detail: "registry not reachable"
409
435
  };
410
- if ("local" === e) return {
411
- name: "update",
412
- level: "ok",
413
- value: `${t.latest} published`,
414
- detail: "running a local build"
415
- };
416
- const n = b(t.latest, e) > 0;
436
+ const n = T(t.latest, e) > 0;
417
437
  return {
418
438
  name: "update",
419
439
  level: n ? "warn" : "ok",
@@ -421,25 +441,25 @@ async function C(e) {
421
441
  detail: n ? `running ${e}` : void 0,
422
442
  fix: n ? "npm install -g sheetxl@latest" : void 0
423
443
  };
424
- }(m.version, p)), {
444
+ }(g.version, m)), {
425
445
  product: "SheetXL",
426
- version: m.version,
427
- build: m.build,
446
+ version: g.version,
447
+ build: g.build,
428
448
  surface: t,
429
449
  collectedAt: (/* @__PURE__ */ new Date()).toISOString(),
430
- ok: !g.some((e) => "error" === e.level),
431
- attended: $,
432
- sessions: d,
433
- checks: g,
434
- host: a ? B() : void 0
450
+ ok: !$.some((e) => "error" === e.level),
451
+ attended: N,
452
+ sessions: f,
453
+ checks: $,
454
+ host: a ? I() : void 0
435
455
  };
436
456
  }
437
- async function E(e, t) {
457
+ async function M(e, t) {
438
458
  if (e.sessions) return [...await e.sessions()];
439
459
  if (t) return [];
440
460
  try {
441
- const e = await k();
442
- return e ? (await x(e)).map((e) => ({
461
+ const e = await j();
462
+ return e ? (await b(e)).map((e) => ({
443
463
  id: e.id,
444
464
  name: e.name,
445
465
  kind: "attended",
@@ -452,7 +472,7 @@ async function E(e, t) {
452
472
  return [];
453
473
  }
454
474
  }
455
- function B() {
475
+ function I() {
456
476
  const e = n.cpus(), t = process.memoryUsage(), o = n.totalmem();
457
477
  return {
458
478
  platform: n.platform(),
@@ -470,31 +490,31 @@ function B() {
470
490
  configStore: s.join(n.homedir(), ".config", "configstore", "sheetxl.json")
471
491
  };
472
492
  }
473
- var L = {
493
+ var J = {
474
494
  ok: " ",
475
495
  warn: "!",
476
496
  error: "✗"
477
- }, D = (e, n) => "error" === e ? t.red(n) : "warn" === e ? t.yellow(n) : t.white(n);
478
- function I(e) {
497
+ }, H = (e, n) => "error" === e ? t.red(n) : "warn" === e ? t.yellow(n) : t.white(n);
498
+ function W(e) {
479
499
  const t = e.ok ? "engine ready" : "not ready", n = e.attended ? "attended" : "unattended";
480
- return `${e.product} — ${t} · ${n} · as of ${J(e.collectedAt)}`;
500
+ return `${e.product} — ${t} · ${n} · as of ${U(e.collectedAt)}`;
481
501
  }
482
- function J(e) {
502
+ function U(e) {
483
503
  const t = new Date(e);
484
504
  return Number.isNaN(t.getTime()) ? "unknown" : t.toTimeString().slice(0, 8);
485
505
  }
486
- function M(e) {
506
+ function K(e) {
487
507
  const n = e.checks, s = Math.max(...n.map((e) => e.name.length)) + 2, o = " ".repeat(s + 4), r = [];
488
- r.push(e.ok ? t.cyanBright(I(e)) : t.yellow(I(e))), r.push("");
508
+ r.push(e.ok ? t.cyanBright(W(e)) : t.yellow(W(e))), r.push("");
489
509
  for (const e of n) {
490
- const n = "ok" === e.level ? " " : D(e.level, L[e.level]), i = t.dim(e.name.padEnd(s)), a = e.detail && e.detail.length <= 44 ? ` ${t.dim(`· ${e.detail}`)}` : "";
491
- r.push(` ${n} ${i}${D(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)}`);
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)}`);
492
512
  }
493
513
  return r.join("\n");
494
514
  }
495
- function W(e) {
515
+ function V(e) {
496
516
  const t = [];
497
- t.push(`**${I(e)}**`), t.push("");
517
+ t.push(`**${W(e)}**`), t.push("");
498
518
  for (const n of e.checks) {
499
519
  const e = "ok" === n.level ? "" : "warn" === n.level ? "⚠ " : "✗ ", s = n.detail ? ` — ${n.detail}` : "";
500
520
  t.push(`- ${e}**${n.name}**: ${n.value}${s}`);
@@ -508,7 +528,7 @@ function W(e) {
508
528
  n.kind,
509
529
  void 0 === n.hasView ? null : n.hasView ? "view" : "headless",
510
530
  n.active ? "active" : null
511
- ].filter(Boolean).join(", "), s = n.path ? ` path: \`${n.path}\`` : "", o = void 0 !== n.openedAt ? ` open since ${J(new Date(n.openedAt).toISOString())}` : "";
531
+ ].filter(Boolean).join(", "), s = n.path ? ` path: \`${n.path}\`` : "", o = void 0 !== n.openedAt ? ` open since ${U(new Date(n.openedAt).toISOString())}` : "";
512
532
  t.push(`- **${n.name}** id: \`${n.id}\` (${e})${s}${o}`);
513
533
  }
514
534
  }
@@ -519,63 +539,63 @@ function W(e) {
519
539
  }
520
540
  return t.join("\n");
521
541
  }
522
- var H = "SHEETXL_TOOL_LOG", U = /* @__PURE__ */ new Set([
542
+ var X = "SHEETXL_TOOL_LOG", F = /* @__PURE__ */ new Set([
523
543
  "code",
524
544
  "source",
525
545
  "script",
526
546
  "argv"
527
- ]), V = /(^|[._-])(key|token|secret|password|credential)s?($|[._-])|licen[cs]e/i, K = null, X = null, R = Promise.resolve(), z = {}, F = null;
528
- function G(e) {
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) {
529
549
  const t = function() {
530
- const e = process.env[H];
550
+ const e = process.env[X];
531
551
  if (void 0 === e) return null;
532
552
  const t = e.trim();
533
553
  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);
534
554
  }();
535
- if (!t) return K = null, null;
555
+ if (!t) return Y = null, null;
536
556
  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`;
537
- return K = s.join(t, i), z = { transport: e.transport }, K;
557
+ return Y = s.join(t, i), q = { transport: e.transport }, Y;
538
558
  }
539
- function Y() {
540
- return K;
559
+ function ee() {
560
+ return Y;
541
561
  }
542
- function q() {
543
- return null !== K;
562
+ function te() {
563
+ return null !== Y;
544
564
  }
545
- function Q(e) {
546
- z = {
547
- ...z,
565
+ function ne(e) {
566
+ q = {
567
+ ...q,
548
568
  ...e
549
569
  };
550
570
  }
551
- function Z(e) {
552
- F = e;
571
+ function se(e) {
572
+ Q = e;
553
573
  }
554
- function ee(e, t) {
574
+ function oe(e, t) {
555
575
  return e.length <= t ? e : e.slice(0, t) + "…[truncated]";
556
576
  }
557
- function te(e, t) {
558
- if (V.test(e)) return "[redacted]";
559
- const n = U.has(e) ? 16384 : 2048;
560
- return "string" == typeof t ? ee(t, n) : Array.isArray(t) ? t.map((t) => te(e, t)) : t && "object" == typeof t ? Object.fromEntries(Object.entries(t).filter(([, e]) => void 0 !== e).map(([t, n]) => [t, te(U.has(e) ? e : t, n)])) : t;
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;
561
581
  }
562
- function ne(e) {
563
- return null == e ? e : te("", e);
582
+ function ie(e) {
583
+ return null == e ? e : re("", e);
564
584
  }
565
- function se(e) {
566
- return ee(e, 2048);
585
+ function ae(e) {
586
+ return oe(e, 2048);
567
587
  }
568
- function oe(e) {
569
- const t = K;
570
- if (!t && !F) return;
588
+ function le(e) {
589
+ const t = Y;
590
+ if (!t && !Q) return;
571
591
  const n = {
572
592
  ts: (/* @__PURE__ */ new Date()).toISOString(),
573
593
  pid: process.pid,
574
- ...z,
594
+ ...q,
575
595
  ...e
576
596
  };
577
- if (F) try {
578
- F(n);
597
+ if (Q) try {
598
+ Q(n);
579
599
  } catch {}
580
600
  if (!t) return;
581
601
  let o;
@@ -586,16 +606,16 @@ function oe(e) {
586
606
  _dropped: !0,
587
607
  _bytes: o.length
588
608
  },
589
- resultPreview: n.resultPreview ? ee(n.resultPreview, 1024) : void 0
609
+ resultPreview: n.resultPreview ? oe(n.resultPreview, 1024) : void 0
590
610
  }));
591
611
  } catch {
592
612
  return;
593
613
  }
594
- R = R.then(async () => {
595
- X || (X = a(s.dirname(t), { recursive: !0 }).then(() => {})), await X, await i(t, o + "\n", "utf-8");
614
+ G = G.then(async () => {
615
+ z || (z = a(s.dirname(t), { recursive: !0 }).then(() => {})), await z, await i(t, o + "\n", "utf-8");
596
616
  }).catch(() => {});
597
617
  }
598
- function re() {
599
- return R;
618
+ function ce() {
619
+ return G;
600
620
  }
601
- export { S as CLAUDE_CODE_FIX, A as GENERIC_FIX, H as TOOL_LOG_ENV, ne as capArgs, se as capPreview, j as checkForUpdate, C as collectInfo, b as compareVersions, k as discoverRelay, x as fetchRelayWorkbooks, T as findMcpRegistrations, re as flushToolLog, Y as getToolLogPath, G as initToolLog, q as isToolLogEnabled, oe as logToolCall, v as printMarkdown, M as renderInfo, W as renderInfoMarkdown, Q as setToolLogContext, Z as setToolLogMirror };
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 };
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.7.28-beta.4",
4
+ "version": "0.8.0-beta.2",
5
5
  "license": "SEE LICENSE IN <LICENSE>",
6
6
  "type": "module",
7
7
  "exports": {
@@ -116,6 +116,7 @@ export declare namespace Info {
116
116
  readonly product: 'SheetXL';
117
117
  /** Engine version, or `local` in a workspace build. */
118
118
  readonly version: string;
119
+ /** When the engine was built (ISO 8601), or null when unstamped. */
119
120
  readonly build: string | null;
120
121
  readonly surface: Surface;
121
122
  /**
@@ -204,6 +205,15 @@ export declare namespace Info {
204
205
  readonly includeHost?: boolean;
205
206
  /** Directory relative paths resolve against, when the surface has its own notion of one. */
206
207
  readonly workspace?: string;
208
+ /**
209
+ * How the reader types the API lookup where this report is shown.
210
+ *
211
+ * @remarks
212
+ * Defaults from the surface — `sheetxl api` for the CLI, `api` (the tool name) for MCP. Given
213
+ * by a caller that is neither: an interactive session reports through the CLI's collector but
214
+ * spells the command `.api`, and the report names it to be typed.
215
+ */
216
+ readonly apiCommand?: string;
207
217
  }
208
218
  }
209
219
  //# sourceMappingURL=InfoTypes.d.ts.map
@@ -0,0 +1,32 @@
1
+ /**
2
+ * How a build identifies itself across every surface that prints one.
3
+ *
4
+ * @remarks
5
+ * Duplicated from the engine's own `getBuildLabel` rather than imported, for the reason given on
6
+ * {@link Info.LicenseSource}: this package sits BELOW `@sheetxl/sdk` and cannot depend on it. The
7
+ * rule is small enough to state twice and the two must not drift — `--version`, the license banner
8
+ * and `info` are read side by side, and a build that names itself differently in each is exactly
9
+ * what makes a bug report ambiguous.
10
+ */
11
+ /**
12
+ * `2026-09-15 14:32` — local time, to the minute.
13
+ *
14
+ * @remarks
15
+ * Local rather than UTC because it is read beside the clock of the machine that did the build,
16
+ * and to the minute because a workspace is rebuilt several times a day; a bare date cannot tell
17
+ * this build from the one before lunch. Unparseable input is handed back untouched — a stamp we
18
+ * cannot read is still evidence, and swallowing it would hide the real problem.
19
+ */
20
+ export declare function formatBuildInstant(iso: string): string;
21
+ /**
22
+ * The stamped version, or `local` plus when it was built.
23
+ *
24
+ * @param version The build stamp, or `local`/empty in a workspace build.
25
+ * @param date When it was built (ISO 8601), or null when unstamped.
26
+ *
27
+ * @remarks
28
+ * A released version already carries its commit (`0.8.0-beta.1+sites.188.9ffc18f87`), so the time
29
+ * adds nothing. A workspace build has no identity at all except when it was built.
30
+ */
31
+ export declare function formatBuildLabel(version: string | null | undefined, date: string | null | undefined): string;
32
+ //# sourceMappingURL=buildLabel.d.ts.map
@@ -1,4 +1,5 @@
1
1
  export * from './InfoTypes';
2
+ export * from './buildLabel';
2
3
  export * from './collectInfo';
3
4
  export * from './renderInfo';
4
5
  export * from './relay';
@@ -27,4 +27,11 @@ export interface PrintMarkdownOptions {
27
27
  * Non-TTY output is verbatim.
28
28
  */
29
29
  export declare const printMarkdown: (md: string, options?: PrintMarkdownOptions) => void;
30
+ /**
31
+ * The text {@link printMarkdown} would write, for a caller that does its own writing — a REPL
32
+ * `writer` hands node a string rather than printing one.
33
+ *
34
+ * @param stream The stream the text is bound for; styling follows its TTY-ness. Defaults to stdout.
35
+ */
36
+ export declare const styleMarkdown: (md: string, stream?: NodeJS.WriteStream) => string;
30
37
  //# sourceMappingURL=printMarkdown.d.ts.map