@bendyline/gezel-cli 1.2.2 → 1.2.3

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
@@ -54,17 +54,26 @@ With no connection flags, the CLI follows this order:
54
54
  service that stops with the command. The interactive TUI
55
55
  retains ownership when it starts a daemon itself, so exiting the TUI runs
56
56
  the daemon's complete shutdown path and cleans up its local engine children.
57
- 3. On first use, the terminal waits while the Gezel app asks you to approve
58
- **Gezel CLI**. The terminal shows a six-character code that you enter in
59
- the app to confirm that you initiated the request. The resulting revocable,
60
- CLI-scoped credential is saved under `~/.gezel/cli/tokens/`. Its logical
61
- local key survives daemon port and certificate rotation.
57
+
58
+ For the per-user local daemon, the CLI connects with your same-user owner
59
+ credential from the protected runtime directory. This works on first use and
60
+ when adopting an already-running daemon, with no desktop approval prompt. The
61
+ npm package is sufficient for local CLI use; you do not need to install or open
62
+ the desktop app.
62
63
 
63
64
  `gezel run` has one deliberate lifecycle exception: if no user daemon exists,
64
65
  it starts a user-role service in-process for that one invocation and stops it
65
66
  afterward. It does not take that fallback after a denied grant or when a live
66
67
  daemon is unhealthy.
67
68
 
69
+ External service connections use a separate authorization path: an explicit
70
+ `--connect <url>`, or an older `legacy-full` machine service selected in step 1,
71
+ requires a CLI-scoped grant. If there is no valid saved grant or supplied
72
+ `--token`, the terminal shows a six-character code and waits for you to approve
73
+ **Gezel CLI** in the Gezel app. The resulting revocable credential is saved
74
+ under `~/.gezel/cli/tokens/` for that service. A valid saved grant or explicit
75
+ `--token` lets the connection proceed without that interaction.
76
+
68
77
  The per-user daemon owns gezels, projects, settings, credentials, and
69
78
  conversations with ordinary user filesystem permissions. It discovers the
70
79
  machine engine broker independently for centralized model downloads and local
@@ -2538,7 +2538,7 @@ knowledge.command("init <dir>").description("Scaffold a catalog folder (catalog.
2538
2538
  const { runKnowledgeInit } = await loadKnowledgeCommand();
2539
2539
  await runKnowledgeInit(dir);
2540
2540
  });
2541
- knowledge.command("build <dir>").description("Compile a catalog folder into a .gezk archive").option("--out <file>", "output path (default <dir>/<id>-<version>.gezk)").option("--sign-key <pemfile>", "Ed25519 private key (PKCS#8 PEM) to sign the manifest").action(async (dir, opts) => {
2541
+ knowledge.command("build <dir>").description("Compile a catalog folder into a .gezk archive").option("--out <file>", "output path (default <dir>/<id>-<version>.gezk)").option("--sign-key <pemfile>", "Ed25519 private key (PKCS#8 PEM) to sign the manifest").option("--skip-images", "Build without image assets, keeping image alt text").action(async (dir, opts) => {
2542
2542
  const { runKnowledgeBuild } = await loadKnowledgeCommand();
2543
2543
  await runKnowledgeBuild(dir, opts);
2544
2544
  });
@@ -2559,10 +2559,20 @@ knowledge.command("export-parquet <path>").description(
2559
2559
  const { runKnowledgeExportParquet } = await loadKnowledgeCommand();
2560
2560
  await runKnowledgeExportParquet(path, opts);
2561
2561
  });
2562
- knowledge.command("search <path> <query>").description("Search a catalog file offline (full-text; --semantic adds vector search)").option("--semantic", "embed the query with the catalog profile (loads the model)").option("--limit <n>", "maximum results", (v) => Number.parseInt(v, 10), 10).action(async (path, query, opts) => {
2562
+ knowledge.command("search <path> <query>").description("Search a catalog file offline (full-text; --semantic adds vector search)").option("--semantic", "embed the query with the catalog profile (loads the model)").option("--latitude <degrees>", "radius center latitude", Number).option("--longitude <degrees>", "radius center longitude", Number).option("--radius-meters <meters>", "subject radius in meters", Number).option("--limit <n>", "maximum results", (v) => Number.parseInt(v, 10), 10).action(async (path, query, opts) => {
2563
2563
  const { runKnowledgeSearch } = await loadKnowledgeCommand();
2564
2564
  await runKnowledgeSearch(path, query, opts);
2565
2565
  });
2566
+ knowledge.command("nearby <path>").description("Find articles near a coordinate in a catalog file, offline").requiredOption("--latitude <degrees>", "center latitude", Number).requiredOption("--longitude <degrees>", "center longitude", Number).requiredOption("--radius-meters <meters>", "subject radius in meters", Number).option("--limit <n>", "page size (maximum 500)", Number, 50).option("--json", "emit document metadata and distances as JSON").action(
2567
+ async (path, opts) => {
2568
+ const { runKnowledgeNearby } = await loadKnowledgeCommand();
2569
+ await runKnowledgeNearby(
2570
+ path,
2571
+ { latitude: opts.latitude, longitude: opts.longitude, radiusMeters: opts.radiusMeters },
2572
+ opts
2573
+ );
2574
+ }
2575
+ );
2566
2576
  knowledge.command("available").description("List the knowledge catalogs the gilde offers for download").action(async () => {
2567
2577
  const client = await connectOwned(cliGlobals());
2568
2578
  const { catalogs } = await client.listAvailableKnowledgeCatalogs();
@@ -6,7 +6,11 @@ import { existsSync } from "fs";
6
6
  import { mkdir as mkdir2, mkdtemp, readFile as readFile2, readdir, rm as rm2, stat, writeFile as writeFile2 } from "fs/promises";
7
7
  import { homedir as homedir2, tmpdir } from "os";
8
8
  import { basename as basename2, dirname as dirname2, isAbsolute, join as join2, relative, resolve as resolve2 } from "path";
9
- import { KnowledgeIdSchema, formatKnowledgeUri } from "@bendyline/gezel";
9
+ import {
10
+ KnowledgeIdSchema,
11
+ KnowledgeRadiusSchema,
12
+ formatKnowledgeUri
13
+ } from "@bendyline/gezel";
10
14
  import {
11
15
  CatalogHandle,
12
16
  EmbedderUnavailableError,
@@ -205,6 +209,7 @@ async function runKnowledgeBuild(dir, opts, deps = {}) {
205
209
  uri: { publisherId: config.publisher.id, catalogId: config.id },
206
210
  ...config.ignore ? { ignore: config.ignore } : {},
207
211
  toc,
212
+ skipImages: opts.skipImages ?? false,
208
213
  onWarning: (message) => console.warn(`warning: ${message}`)
209
214
  });
210
215
  console.log(`Content: ${displayPath(root, contentRoot)}`);
@@ -248,6 +253,8 @@ async function runKnowledgeBuild(dir, opts, deps = {}) {
248
253
  countTokens: (text) => embedder.countTokens(text),
249
254
  workDir,
250
255
  assets: source.assets,
256
+ invalidAssets: "warn",
257
+ onWarning: (message) => console.warn(`warning: ${message}`),
251
258
  ...signKeyPem ? { finalizeManifest: (manifest) => signManifest(manifest, signKeyPem) } : {},
252
259
  onProgress: ({ done, total }) => {
253
260
  if (!process.stderr.isTTY || total === 0) return;
@@ -324,6 +331,16 @@ async function runKnowledgeInspect(path) {
324
331
  for (const [key, value] of rows) console.log(`${key.padEnd(width)} ${value}`);
325
332
  }
326
333
  async function runKnowledgeSearch(path, query, opts, deps = {}) {
334
+ const supplied = [opts.latitude, opts.longitude, opts.radiusMeters].filter(
335
+ (value) => value !== void 0
336
+ ).length;
337
+ if (supplied !== 0 && supplied !== 3)
338
+ throw new CliError("Provide --latitude, --longitude and --radius-meters together.");
339
+ const spatial = supplied ? KnowledgeRadiusSchema.parse({
340
+ latitude: opts.latitude,
341
+ longitude: opts.longitude,
342
+ radiusMeters: opts.radiusMeters
343
+ }) : void 0;
327
344
  const limit = Math.min(50, Math.max(1, opts.limit ?? 10));
328
345
  const { rootDir, cleanup } = await materializeCatalog(path);
329
346
  try {
@@ -332,7 +349,8 @@ async function runKnowledgeSearch(path, query, opts, deps = {}) {
332
349
  );
333
350
  const handle = CatalogHandle.open(rootDir);
334
351
  try {
335
- const docHits = handle.searchDocumentsFts(query, limit);
352
+ const allowed = spatial ? new Set(handle.spatialMatches(spatial).keys()) : void 0;
353
+ const docHits = handle.searchDocumentsFts(query, limit, allowed);
336
354
  if (docHits.length > 0) {
337
355
  console.log("Documents:");
338
356
  for (const hit of docHits) {
@@ -345,7 +363,8 @@ async function runKnowledgeSearch(path, query, opts, deps = {}) {
345
363
  let chunkHits = handle.searchChunksFts(
346
364
  query,
347
365
  handle.shards.map((s) => s.id),
348
- Math.ceil(limit / Math.max(1, handle.shards.length))
366
+ Math.ceil(limit / Math.max(1, handle.shards.length)),
367
+ allowed
349
368
  );
350
369
  if (opts.semantic) {
351
370
  const embedder = await (deps.createEmbedder ?? defaultCreateEmbedder)(
@@ -353,7 +372,10 @@ async function runKnowledgeSearch(path, query, opts, deps = {}) {
353
372
  );
354
373
  try {
355
374
  const vector = await embedder.embedQuery(query);
356
- chunkHits = [...handle.searchSemantic(vector, { finalK: limit }), ...chunkHits];
375
+ chunkHits = [
376
+ ...handle.searchSemantic(vector, { finalK: limit, allowedDocumentIds: allowed, query }),
377
+ ...chunkHits
378
+ ];
357
379
  } finally {
358
380
  await embedder.dispose().catch(() => {
359
381
  });
@@ -471,6 +493,33 @@ async function runKnowledgeExportParquet(path, opts) {
471
493
  ` written with DuckDB ${report.duckdbVersion}; report in ${join2(outDir, "parquet-manifest.json")}`
472
494
  );
473
495
  }
496
+ async function runKnowledgeNearby(path, radius, opts = {}) {
497
+ const spatial = KnowledgeRadiusSchema.parse(radius);
498
+ const { rootDir, cleanup } = await materializeCatalog(path);
499
+ try {
500
+ const manifest = JSON.parse(
501
+ await readFile2(join2(rootDir, "manifest.json"), "utf8")
502
+ );
503
+ const handle = CatalogHandle.open(rootDir);
504
+ try {
505
+ const result = handle.nearbyDocuments(spatial, { limit: opts.limit });
506
+ if (opts.json) console.log(JSON.stringify(result, null, 2));
507
+ else {
508
+ console.log(
509
+ `${result.total} articles within ${(spatial.radiusMeters / 1e3).toFixed(1)} km`
510
+ );
511
+ for (const doc of result.documents)
512
+ console.log(
513
+ ` ${(doc.distanceMeters / 1e3).toFixed(2)} km ${doc.title} ${formatKnowledgeUri({ publisherId: manifest.publisher.id, catalogId: manifest.id, documentId: doc.id })}`
514
+ );
515
+ }
516
+ } finally {
517
+ handle.close();
518
+ }
519
+ } finally {
520
+ await cleanup();
521
+ }
522
+ }
474
523
  export {
475
524
  contentSha256,
476
525
  embeddingRuntimeMissingMessage,
@@ -478,6 +527,7 @@ export {
478
527
  runKnowledgeExportParquet,
479
528
  runKnowledgeInit,
480
529
  runKnowledgeInspect,
530
+ runKnowledgeNearby,
481
531
  runKnowledgeSearch,
482
532
  runKnowledgeValidate
483
533
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bendyline/gezel-cli",
3
- "version": "1.2.2",
3
+ "version": "1.2.3",
4
4
  "description": "The `gezel` command-line tool.",
5
5
  "license": "MIT",
6
6
  "keywords": [
@@ -44,15 +44,15 @@
44
44
  "!dist/**/*.map"
45
45
  ],
46
46
  "dependencies": {
47
- "@bendyline/gezel": "1.2.2",
48
- "@bendyline/gezel-app-sdk": "1.1.2",
49
- "@bendyline/gezel-catalog": "1.2.2",
50
- "@bendyline/gezel-client": "1.2.2",
51
- "@bendyline/gezel-knowledge": "1.2.2",
52
- "@bendyline/gezel-service": "1.2.2",
53
- "@bendyline/squisq": "2.11.11",
54
- "@bendyline/squisq-formats": "2.6.11",
55
- "@bendyline/squisq-react": "2.11.13",
47
+ "@bendyline/gezel": "1.2.3",
48
+ "@bendyline/gezel-app-sdk": "1.1.3",
49
+ "@bendyline/gezel-catalog": "1.2.3",
50
+ "@bendyline/gezel-client": "1.2.3",
51
+ "@bendyline/gezel-knowledge": "1.2.3",
52
+ "@bendyline/gezel-service": "1.2.3",
53
+ "@bendyline/squisq": "2.11.13",
54
+ "@bendyline/squisq-formats": "2.6.12",
55
+ "@bendyline/squisq-react": "2.11.15",
56
56
  "commander": "^15.0.0",
57
57
  "ink": "^7.1.1",
58
58
  "ink-text-input": "^6.0.0",