@bendyline/gezel-cli 1.2.0 → 1.2.1

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/README.md CHANGED
@@ -45,7 +45,13 @@ With no connection flags, the CLI follows this order:
45
45
  2. Discover the logged-in user's product daemon through the same pinned
46
46
  runtime discovery used by the Gezel app SDK. Its actual dynamic port and
47
47
  pinned TLS certificate come from `~/.gezel/runtime`; management commands
48
- may start that user-role daemon when it is absent. The interactive TUI
48
+ may start that user-role daemon when it is absent, and say so on stderr
49
+ because it keeps running afterwards (`gezel stop --daemon` ends it). A
50
+ daemon the CLI starts keeps its own log in
51
+ `~/.gezel/logs/service-YYYY-MM-DD.log` (rolled at 10 MB, kept 7 days).
52
+ Read-only diagnostics such as `gezel native status` and `native list`
53
+ never leave one behind: with no daemon running they answer from a
54
+ service that stops with the command. The interactive TUI
49
55
  retains ownership when it starts a daemon itself, so exiting the TUI runs
50
56
  the daemon's complete shutdown path and cleans up its local engine children.
51
57
  3. On first use, the terminal waits while the Gezel app asks you to approve
@@ -218,6 +224,21 @@ you can use:
218
224
  - Gezel and project management (`gezel agent`, `gezel project`, `gezel task`)
219
225
  - Skills and handbook export (`gezel skills convert`, `gezel handboek export`) —
220
226
  these need no running daemon at all
227
+ - Knowledge catalogs you already have: `gezel knowledge validate`, `inspect`
228
+ and full-text `search` work offline, with no daemon
229
+
230
+ Building a catalog (`gezel knowledge build`) and `gezel knowledge search
231
+ --semantic` also need the embedding runtime, which an npm install leaves out.
232
+ Add it where Gezel is installed (drop `-g` for a project install); the desktop
233
+ app already includes it:
234
+
235
+ ```bash
236
+ npm install -g @huggingface/transformers@^3.8.1
237
+ ```
238
+
239
+ In a project install, also add the `overrides` from the
240
+ [`@bendyline/gezel-service` README](https://www.npmjs.com/package/@bendyline/gezel-service):
241
+ Transformers still asks for a `sharp` release that `npm audit` flags.
221
242
 
222
243
  ## Running models on your own machine
223
244
 
@@ -273,7 +273,13 @@ import { createHash, randomUUID } from "crypto";
273
273
  import { chmod, mkdir, readFile, rm, writeFile } from "fs/promises";
274
274
  import { homedir } from "os";
275
275
  import { basename, dirname, join, resolve } from "path";
276
- import { pickRandomNameWithGender } from "@bendyline/gezel";
276
+ import {
277
+ getLogLevel,
278
+ getLogOutput,
279
+ pickRandomNameWithGender,
280
+ setLogLevel,
281
+ setLogOutput
282
+ } from "@bendyline/gezel";
277
283
  import {
278
284
  GezelSdkError,
279
285
  authorizeLocal,
@@ -10,7 +10,13 @@ import { createHash, randomUUID } from "crypto";
10
10
  import { chmod, mkdir, readFile, rm, writeFile } from "fs/promises";
11
11
  import { homedir } from "os";
12
12
  import { basename, dirname, join, resolve } from "path";
13
- import { pickRandomNameWithGender } from "@bendyline/gezel";
13
+ import {
14
+ getLogLevel,
15
+ getLogOutput,
16
+ pickRandomNameWithGender,
17
+ setLogLevel,
18
+ setLogOutput
19
+ } from "@bendyline/gezel";
14
20
  import {
15
21
  GezelSdkError,
16
22
  authorizeLocal,
@@ -4,13 +4,12 @@
4
4
  import { basename as basename4, isAbsolute as isAbsolutePath, join as joinPath } from "path";
5
5
  import {
6
6
  GEZEL_VERSION,
7
- getLogLevel,
8
- getLogOutput,
9
- setLogLevel,
10
- setLogOutput
7
+ getLogLevel as getLogLevel2,
8
+ getLogOutput as getLogOutput2,
9
+ setLogLevel as setLogLevel2,
10
+ setLogOutput as setLogOutput2
11
11
  } from "@bendyline/gezel";
12
12
  import {
13
- GezelApiError as GezelApiError3,
14
13
  streamChatEvents
15
14
  } from "@bendyline/gezel-client";
16
15
  import {
@@ -62,7 +61,13 @@ import { createHash, randomUUID } from "crypto";
62
61
  import { chmod, mkdir, readFile, rm, writeFile } from "fs/promises";
63
62
  import { homedir } from "os";
64
63
  import { basename, dirname, join, resolve } from "path";
65
- import { pickRandomNameWithGender } from "@bendyline/gezel";
64
+ import {
65
+ getLogLevel,
66
+ getLogOutput,
67
+ pickRandomNameWithGender,
68
+ setLogLevel,
69
+ setLogOutput
70
+ } from "@bendyline/gezel";
66
71
  import {
67
72
  GezelSdkError,
68
73
  authorizeLocal,
@@ -84,6 +89,31 @@ import {
84
89
  systemSharedAssetsDir
85
90
  } from "@bendyline/gezel-client/node";
86
91
  import { gezelPaths } from "@bendyline/gezel/paths";
92
+
93
+ // src/signal-cleanup.ts
94
+ function installSignalCleanup(cleanup, options = {}) {
95
+ if (!cleanup) return () => {
96
+ };
97
+ const host = options.host ?? process;
98
+ let cleanupPromise;
99
+ const onSignal = (signal) => {
100
+ host.exitCode = signal === "SIGINT" ? 130 : 143;
101
+ cleanupPromise ??= cleanup().catch((error) => {
102
+ options.onError?.(error);
103
+ host.exitCode = 1;
104
+ });
105
+ };
106
+ const onSigint = () => onSignal("SIGINT");
107
+ const onSigterm = () => onSignal("SIGTERM");
108
+ host.on("SIGINT", onSigint);
109
+ host.on("SIGTERM", onSigterm);
110
+ return () => {
111
+ host.off("SIGINT", onSigint);
112
+ host.off("SIGTERM", onSigterm);
113
+ };
114
+ }
115
+
116
+ // src/connection.ts
87
117
  var CliError = class extends Error {
88
118
  constructor(message) {
89
119
  super(message);
@@ -131,7 +161,7 @@ function resolveDevHome(globals) {
131
161
  process.env.GEZEL_HOME = join(homedir(), ".gezel-dev");
132
162
  }
133
163
  }
134
- async function connectOwned(globals) {
164
+ async function connectOwned(globals, options = {}) {
135
165
  applyHome(globals);
136
166
  const preferred = await connectPreferredService(globals);
137
167
  if (preferred) return preferred.client;
@@ -148,6 +178,9 @@ async function connectOwned(globals) {
148
178
  ...process.env.GEZEL_HOME ? { home: process.env.GEZEL_HOME } : {}
149
179
  }
150
180
  });
181
+ if (authorized.daemon.mode === "spawned" && options.announceSpawn !== false) {
182
+ process.stderr.write(spawnedDaemonNotice(authorized.daemon.pid));
183
+ }
151
184
  const connected = await connectionFromAuthorization(
152
185
  authorized,
153
186
  "The local Gezel owner authorization"
@@ -166,6 +199,8 @@ async function connectForTui(globals) {
166
199
  daemonEntry: resolveDaemonEntry(import.meta.url),
167
200
  detached: false,
168
201
  stdio: "pipe",
202
+ // The pipes below are drained and discarded, so the daemon keeps its own log.
203
+ writeLogFile: true,
169
204
  env: cliUserDaemonEnv(process.env.GEZEL_HOME, await shouldPreferCanonicalPort()),
170
205
  ...process.env.GEZEL_HOME ? { home: process.env.GEZEL_HOME } : {},
171
206
  timeoutMs: 2e4
@@ -279,6 +314,39 @@ async function connectForRun(globals) {
279
314
  };
280
315
  return { kind: "owned", client, baseUrl, stop };
281
316
  }
317
+ function spawnedDaemonNotice(pid) {
318
+ const which = pid === void 0 ? "" : ` (pid ${pid})`;
319
+ return `Started the Gezel background service${which}; it keeps running after this command. Stop it with \`gezel stop --daemon\`.
320
+ `;
321
+ }
322
+ async function withTransientConnection(globals, fn) {
323
+ const previousLogOutput = getLogOutput();
324
+ setLogOutput("stderr");
325
+ const previousLogLevel = getLogLevel();
326
+ if (!process.env.GEZEL_LOG_LEVEL && previousLogLevel === "info") setLogLevel("warn");
327
+ let conn;
328
+ let removeSignalCleanup;
329
+ try {
330
+ conn = await connectForRun(globals);
331
+ removeSignalCleanup = installSignalCleanup(conn.stop, {
332
+ onError: (error) => {
333
+ process.stderr.write(
334
+ `shutdown failed: ${error instanceof Error ? error.message : String(error)}
335
+ `
336
+ );
337
+ }
338
+ });
339
+ return await fn(conn.client);
340
+ } finally {
341
+ removeSignalCleanup?.();
342
+ try {
343
+ if (conn?.stop) await conn.stop();
344
+ } finally {
345
+ setLogOutput(previousLogOutput);
346
+ setLogLevel(previousLogLevel);
347
+ }
348
+ }
349
+ }
282
350
  var CLI_APP_ID_PREFIX = "gezel-cli";
283
351
  var CLI_APPROVAL_TIMEOUT_SEC = 300;
284
352
  var PENDING_GRANT_MINUTES = 10;
@@ -766,7 +834,12 @@ async function waitForTask(client, ref, options) {
766
834
  signal
767
835
  )
768
836
  );
769
- const questionIds = questions.filter((q) => q.taskRef && refs.has(q.taskRef)).map((q) => q.id);
837
+ const questionIds = questions.filter(
838
+ (q) => q.taskRef && refs.has(q.taskRef) && // A service pause card is a historical notification. Actual task
839
+ // status above decides whether it is still paused; real session
840
+ // questions and permissions must continue to block observation.
841
+ !(q.sessionId === "" && q.intent?.kind === "task-paused")
842
+ ).map((q) => q.id);
770
843
  if (questionIds.length) return { task: task2, outcome: "blocked", exitCode: 2, questionIds };
771
844
  }
772
845
  if (budget.expired()) return { task: task2, outcome: "timeout", exitCode: 3 };
@@ -1430,29 +1503,6 @@ function registerProjectSettingsCommands(env2, connect, projectFor) {
1430
1503
  });
1431
1504
  }
1432
1505
 
1433
- // src/signal-cleanup.ts
1434
- function installSignalCleanup(cleanup, options = {}) {
1435
- if (!cleanup) return () => {
1436
- };
1437
- const host = options.host ?? process;
1438
- let cleanupPromise;
1439
- const onSignal = (signal) => {
1440
- host.exitCode = signal === "SIGINT" ? 130 : 143;
1441
- cleanupPromise ??= cleanup().catch((error) => {
1442
- options.onError?.(error);
1443
- host.exitCode = 1;
1444
- });
1445
- };
1446
- const onSigint = () => onSignal("SIGINT");
1447
- const onSigterm = () => onSignal("SIGTERM");
1448
- host.on("SIGINT", onSigint);
1449
- host.on("SIGTERM", onSigterm);
1450
- return () => {
1451
- host.off("SIGINT", onSigint);
1452
- host.off("SIGTERM", onSigterm);
1453
- };
1454
- }
1455
-
1456
1506
  // src/storage-format.ts
1457
1507
  function formatBytes2(bytes) {
1458
1508
  if (bytes >= 1024 ** 3) return `${(bytes / 1024 ** 3).toFixed(1)} GB`;
@@ -1861,7 +1911,7 @@ program.command("start").description("Start the Gezel daemon (no-op if already r
1861
1911
  if (opts.web) await printWebUrl(result.baseUrl, opts.open === true);
1862
1912
  return;
1863
1913
  }
1864
- const client = await connectOwned(cliGlobals());
1914
+ const client = await connectOwned(cliGlobals(), { announceSpawn: false });
1865
1915
  const health = await client.health();
1866
1916
  console.log(`gezeld running (version ${health.version})`);
1867
1917
  });
@@ -2096,10 +2146,10 @@ program.command("run [prompt...]").description("Run a prompt through a gezel and
2096
2146
  process.exitCode = 1;
2097
2147
  return;
2098
2148
  }
2099
- const previousLogOutput = getLogOutput();
2100
- setLogOutput("stderr");
2101
- const previousLogLevel = getLogLevel();
2102
- if (!process.env.GEZEL_LOG_LEVEL && previousLogLevel === "info") setLogLevel("warn");
2149
+ const previousLogOutput = getLogOutput2();
2150
+ setLogOutput2("stderr");
2151
+ const previousLogLevel = getLogLevel2();
2152
+ if (!process.env.GEZEL_LOG_LEVEL && previousLogLevel === "info") setLogLevel2("warn");
2103
2153
  let conn;
2104
2154
  let removeSignalCleanup;
2105
2155
  try {
@@ -2150,8 +2200,8 @@ ${ev.error}`);
2150
2200
  try {
2151
2201
  if (conn?.stop) await conn.stop();
2152
2202
  } finally {
2153
- setLogOutput(previousLogOutput);
2154
- setLogLevel(previousLogLevel);
2203
+ setLogOutput2(previousLogOutput);
2204
+ setLogLevel2(previousLogLevel);
2155
2205
  }
2156
2206
  }
2157
2207
  });
@@ -2506,17 +2556,7 @@ knowledge.command("install <source>").description("Install a .gezk catalog into
2506
2556
  ...opts.private ? { privatePlacement: true } : {}
2507
2557
  });
2508
2558
  const client = await connectOwned(cliGlobals());
2509
- let started;
2510
- try {
2511
- started = await client.installKnowledgeCatalog({ source: installSource });
2512
- } catch (err) {
2513
- if (err instanceof GezelApiError3 && err.status === 403) {
2514
- throw new CliError(
2515
- "Downloading knowledge catalogs needs app network access, which the security policy turns off (Settings \u2192 Security)."
2516
- );
2517
- }
2518
- throw err;
2519
- }
2559
+ const started = await client.installKnowledgeCatalog({ source: installSource });
2520
2560
  if (started.alreadyRunning)
2521
2561
  console.error("Attaching to the install that is already running.");
2522
2562
  let done;
@@ -2864,6 +2904,7 @@ program.command("create-audio [text...]").description("Synthesize speech from te
2864
2904
  `speech synthesis failed: ${err instanceof Error ? err.message : String(err)}`
2865
2905
  );
2866
2906
  }
2907
+ if (!res.artifactPath) throw new CliError("speech synthesis returned no saved audio");
2867
2908
  const dest = await saveArtifact(client, projectId, res.artifactPath, opts.output);
2868
2909
  const m = res.meta;
2869
2910
  console.log(dest);
@@ -2889,12 +2930,18 @@ ${formatNativeStatus(installed)}`
2889
2930
  );
2890
2931
  });
2891
2932
  native.command("list").description("List native executables and their install state").action(async () => {
2892
- const client = await connectOwned(cliGlobals());
2893
- console.log(formatNativeList(await client.getNativeEngineStatus()));
2933
+ const status = await withTransientConnection(
2934
+ cliGlobals(),
2935
+ (client) => client.getNativeEngineStatus()
2936
+ );
2937
+ console.log(formatNativeList(status));
2894
2938
  });
2895
2939
  native.command("status").description("Show native release, platform, backend, and toolkit status").action(async () => {
2896
- const client = await connectOwned(cliGlobals());
2897
- console.log(formatNativeStatus(await client.getNativeEngineStatus()));
2940
+ const status = await withTransientConnection(
2941
+ cliGlobals(),
2942
+ (client) => client.getNativeEngineStatus()
2943
+ );
2944
+ console.log(formatNativeStatus(status));
2898
2945
  });
2899
2946
  var image = program.command("image").description("Manage image-generation models");
2900
2947
  image.command("status").description("Show the image engine status and local model count").action(async () => {
package/dist/bin/gezel.js CHANGED
@@ -1,6 +1,22 @@
1
1
  #!/usr/bin/env node
2
2
 
3
+ // src/bin/node-version.ts
4
+ var MINIMUM_NODE_MAJOR = 24;
5
+ function unsupportedNodeMessage(version) {
6
+ const major = Number.parseInt(version, 10);
7
+ if (!Number.isFinite(major) || major >= MINIMUM_NODE_MAJOR) return void 0;
8
+ return `Gezel needs Node.js ${MINIMUM_NODE_MAJOR} or newer (found v${version}).
9
+ Install Node.js ${MINIMUM_NODE_MAJOR} or later from https://nodejs.org, then run the command again.
10
+ `;
11
+ }
12
+
3
13
  // src/bin/gezel-launcher.ts
4
14
  if (!process.env.NODE_ENV) process.env.NODE_ENV = "production";
5
15
  var mainModule = "./gezel-main.js";
6
- await import(mainModule);
16
+ var unsupported = unsupportedNodeMessage(process.versions.node);
17
+ if (unsupported) {
18
+ process.stderr.write(unsupported);
19
+ process.exitCode = 1;
20
+ } else {
21
+ await import(mainModule);
22
+ }
@@ -12,6 +12,7 @@ import {
12
12
  EmbedderUnavailableError,
13
13
  KNOWLEDGE_EMBEDDING_PROFILES,
14
14
  MARKDOWN_CHUNKS_2,
15
+ TRANSFORMERS_PEER_RANGE,
15
16
  compileKnowledgeCatalog,
16
17
  createProfileEmbedder,
17
18
  detectTableOfContents,
@@ -29,7 +30,13 @@ import { createHash, randomUUID } from "crypto";
29
30
  import { chmod, mkdir, readFile, rm, writeFile } from "fs/promises";
30
31
  import { homedir } from "os";
31
32
  import { basename, dirname, join, resolve } from "path";
32
- import { pickRandomNameWithGender } from "@bendyline/gezel";
33
+ import {
34
+ getLogLevel,
35
+ getLogOutput,
36
+ pickRandomNameWithGender,
37
+ setLogLevel,
38
+ setLogOutput
39
+ } from "@bendyline/gezel";
33
40
  import {
34
41
  GezelSdkError,
35
42
  authorizeLocal,
@@ -76,10 +83,22 @@ async function defaultCreateEmbedder(profileId) {
76
83
  try {
77
84
  return await createProfileEmbedder(profile, { cacheDir: hfCacheDir() });
78
85
  } catch (err) {
79
- if (err instanceof EmbedderUnavailableError) throw new CliError(err.message);
86
+ if (err instanceof EmbedderUnavailableError) {
87
+ throw new CliError(err.runtimeMissing ? embeddingRuntimeMissingMessage() : err.message);
88
+ }
80
89
  throw err;
81
90
  }
82
91
  }
92
+ function embeddingRuntimeMissingMessage() {
93
+ const spec = `@huggingface/transformers@${TRANSFORMERS_PEER_RANGE}`;
94
+ return [
95
+ "Building a catalog and --semantic search need the embedding runtime, which an npm install of Gezel leaves out.",
96
+ "Add it where Gezel is installed:",
97
+ ` npm install -g ${spec} if you installed gezel with npm install -g`,
98
+ ` npm install ${spec} in the project where you installed gezel`,
99
+ "The Gezel desktop app already includes it, and full-text search works without it."
100
+ ].join("\n");
101
+ }
83
102
  async function runKnowledgeInit(dir) {
84
103
  const root = resolve2(dir);
85
104
  const configPath = join2(root, CATALOG_JSON);
@@ -427,6 +446,7 @@ async function runKnowledgeExportParquet(path, opts) {
427
446
  }
428
447
  export {
429
448
  contentSha256,
449
+ embeddingRuntimeMissingMessage,
430
450
  runKnowledgeBuild,
431
451
  runKnowledgeExportParquet,
432
452
  runKnowledgeInit,
package/dist/tui/index.js CHANGED
@@ -15,7 +15,13 @@ import { createHash, randomUUID } from "crypto";
15
15
  import { chmod, mkdir, readFile, rm, writeFile } from "fs/promises";
16
16
  import { homedir } from "os";
17
17
  import { basename, dirname, join, resolve } from "path";
18
- import { pickRandomNameWithGender } from "@bendyline/gezel";
18
+ import {
19
+ getLogLevel,
20
+ getLogOutput,
21
+ pickRandomNameWithGender,
22
+ setLogLevel,
23
+ setLogOutput
24
+ } from "@bendyline/gezel";
19
25
  import {
20
26
  GezelSdkError,
21
27
  authorizeLocal,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bendyline/gezel-cli",
3
- "version": "1.2.0",
3
+ "version": "1.2.1",
4
4
  "description": "The `gezel` command-line tool.",
5
5
  "license": "MIT",
6
6
  "keywords": [
@@ -44,12 +44,12 @@
44
44
  "!dist/**/*.map"
45
45
  ],
46
46
  "dependencies": {
47
- "@bendyline/gezel": "1.2.0",
48
- "@bendyline/gezel-app-sdk": "1.1.0",
49
- "@bendyline/gezel-catalog": "1.2.0",
50
- "@bendyline/gezel-client": "1.2.0",
51
- "@bendyline/gezel-knowledge": "1.2.0",
52
- "@bendyline/gezel-service": "1.2.0",
47
+ "@bendyline/gezel": "1.2.1",
48
+ "@bendyline/gezel-app-sdk": "1.1.1",
49
+ "@bendyline/gezel-catalog": "1.2.1",
50
+ "@bendyline/gezel-client": "1.2.1",
51
+ "@bendyline/gezel-knowledge": "1.2.1",
52
+ "@bendyline/gezel-service": "1.2.1",
53
53
  "@bendyline/squisq": "2.11.11",
54
54
  "@bendyline/squisq-formats": "2.6.11",
55
55
  "@bendyline/squisq-react": "2.11.13",