dsh-locator 0.8.2 → 0.10.0
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/CHANGELOG.md +47 -0
- package/README-es.md +30 -5
- package/README-hi.md +31 -5
- package/README-pt.md +31 -5
- package/README.en.md +31 -5
- package/README.md +31 -5
- package/bin/darwin-arm64/indexd +0 -0
- package/bin/darwin-x64/indexd +0 -0
- package/bin/linux-arm64/indexd +0 -0
- package/bin/linux-x64/indexd +0 -0
- package/bin/win32-arm64/indexd.exe +0 -0
- package/bin/win32-x64/indexd.exe +0 -0
- package/client.js +1198 -117
- package/lib/combined.d.ts +20 -3
- package/lib/combined.d.ts.map +1 -1
- package/lib/combined.js +85 -15
- package/lib/combined.js.map +1 -1
- package/lib/content-search-worker.d.ts +8 -3
- package/lib/content-search-worker.d.ts.map +1 -1
- package/lib/content-search-worker.js +54 -27
- package/lib/content-search-worker.js.map +1 -1
- package/lib/content-search.d.ts +127 -7
- package/lib/content-search.d.ts.map +1 -1
- package/lib/content-search.js +571 -36
- package/lib/content-search.js.map +1 -1
- package/lib/content.d.ts +83 -5
- package/lib/content.d.ts.map +1 -1
- package/lib/content.js +351 -87
- package/lib/content.js.map +1 -1
- package/lib/export.d.ts +61 -0
- package/lib/export.d.ts.map +1 -1
- package/lib/export.js +217 -52
- package/lib/export.js.map +1 -1
- package/lib/find.d.ts.map +1 -1
- package/lib/find.js +73 -16
- package/lib/find.js.map +1 -1
- package/lib/http.d.ts +38 -2
- package/lib/http.d.ts.map +1 -1
- package/lib/http.js +279 -82
- package/lib/http.js.map +1 -1
- package/lib/reveal.d.ts +69 -3
- package/lib/reveal.d.ts.map +1 -1
- package/lib/reveal.js +140 -11
- package/lib/reveal.js.map +1 -1
- package/lib/tools.d.ts +30 -0
- package/lib/tools.d.ts.map +1 -1
- package/lib/tools.js +65 -3
- package/lib/tools.js.map +1 -1
- package/package.json +1 -1
- package/src/combined.ts +107 -17
- package/src/content-search-worker.ts +52 -24
- package/src/content-search.ts +710 -36
- package/src/content.ts +349 -73
- package/src/export.ts +240 -50
- package/src/find.ts +83 -16
- package/src/http.ts +271 -83
- package/src/reveal.ts +148 -10
- package/src/tools.ts +83 -6
package/src/export.ts
CHANGED
|
@@ -5,13 +5,31 @@
|
|
|
5
5
|
* page and writes a normal SQLite database so external tools can query it.
|
|
6
6
|
* `node:sqlite` is loaded lazily: hosts below Node 22.5 get a clear error
|
|
7
7
|
* instead of a plugin that fails to load.
|
|
8
|
+
*
|
|
9
|
+
* The export is a *controlled* write, not an arbitrary filesystem write:
|
|
10
|
+
* - the target must live inside the plugin state directory unless the caller
|
|
11
|
+
* explicitly opts into an outside path (`allowOutsideStateDir`), and a
|
|
12
|
+
* relative path always resolves inside the state directory;
|
|
13
|
+
* - an existing target is only replaced when it is a database this tool
|
|
14
|
+
* created (SQLite header + our `user_version` marker + the `entries`
|
|
15
|
+
* schema), so `overwrite` can never clobber an unrelated file;
|
|
16
|
+
* - the database is built in a sibling temporary file and moved into place
|
|
17
|
+
* with an atomic rename, so a failed export never leaves a half-written
|
|
18
|
+
* database at the requested path.
|
|
8
19
|
* @module dsh-locator/export
|
|
9
20
|
*/
|
|
10
21
|
|
|
11
|
-
import { existsSync, mkdirSync, rmSync, statSync } from 'node:fs'
|
|
12
|
-
import { dirname, isAbsolute, resolve } from 'node:path'
|
|
22
|
+
import { existsSync, mkdirSync, renameSync, rmSync, statSync } from 'node:fs'
|
|
23
|
+
import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
|
|
13
24
|
import { defineTool } from '@deepseek-ai/dsh-tools'
|
|
14
25
|
import type { LocatorRuntime } from './runtime.ts'
|
|
26
|
+
import { resolveWithinRoots } from './reveal.ts'
|
|
27
|
+
|
|
28
|
+
/** `PRAGMA user_version` stamped into every database this tool creates. */
|
|
29
|
+
export const EXPORT_DB_USER_VERSION = 1
|
|
30
|
+
|
|
31
|
+
/** Default file name inside the state directory when `path` is omitted. */
|
|
32
|
+
export const DEFAULT_EXPORT_NAME = 'locator-export.sqlite'
|
|
15
33
|
|
|
16
34
|
const OUTPUT_SCHEMA = {
|
|
17
35
|
type: 'object',
|
|
@@ -26,6 +44,104 @@ const OUTPUT_SCHEMA = {
|
|
|
26
44
|
},
|
|
27
45
|
} as const
|
|
28
46
|
|
|
47
|
+
/** Minimal shape of `node:sqlite` used here (the real typings are platform-dependent). */
|
|
48
|
+
interface SqliteDatabaseLike {
|
|
49
|
+
exec(sql: string): unknown
|
|
50
|
+
prepare(sql: string): {
|
|
51
|
+
run(...parameters: unknown[]): unknown
|
|
52
|
+
get(...parameters: unknown[]): unknown
|
|
53
|
+
}
|
|
54
|
+
close(): void
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** The lazily imported `node:sqlite` module slice. */
|
|
58
|
+
export interface SqliteModuleLike {
|
|
59
|
+
DatabaseSync: new (path: string, options?: { readOnly?: boolean }) => SqliteDatabaseLike
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** Authorization result for one export target. */
|
|
63
|
+
export type ExportTargetResult =
|
|
64
|
+
| { ok: true; path: string }
|
|
65
|
+
| { ok: false; error: string }
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Authorize the requested export path.
|
|
69
|
+
*
|
|
70
|
+
* With no `path`, the export goes to `<stateDir>/locator-export.sqlite`. A
|
|
71
|
+
* relative path resolves inside the state directory (and may not escape it by
|
|
72
|
+
* `..`). An absolute path is accepted only inside the state directory unless
|
|
73
|
+
* the caller explicitly passes `allowOutsideStateDir`.
|
|
74
|
+
* @param requested - raw `path` argument, if any.
|
|
75
|
+
* @param stateDir - the plugin's state directory.
|
|
76
|
+
* @param allowOutsideStateDir - explicit opt-in for an absolute path elsewhere.
|
|
77
|
+
* @returns the absolute output path, or a refusal message.
|
|
78
|
+
*/
|
|
79
|
+
export function resolveExportTarget(
|
|
80
|
+
requested: string | undefined,
|
|
81
|
+
stateDir: string,
|
|
82
|
+
allowOutsideStateDir: boolean,
|
|
83
|
+
): ExportTargetResult {
|
|
84
|
+
const state = resolve(stateDir)
|
|
85
|
+
const raw = typeof requested === 'string' ? requested.trim() : ''
|
|
86
|
+
if (raw === '') return { ok: true, path: resolve(state, DEFAULT_EXPORT_NAME) }
|
|
87
|
+
const candidate = isAbsolute(raw) ? resolve(raw) : resolve(state, raw)
|
|
88
|
+
if (isAbsolute(raw) && !allowOutsideStateDir) {
|
|
89
|
+
const inside = resolveWithinRoots(candidate, [state])
|
|
90
|
+
if (inside === undefined) {
|
|
91
|
+
return {
|
|
92
|
+
ok: false,
|
|
93
|
+
error: `path must stay inside the plugin state directory (${state}); pass allowOutsideStateDir: true to export elsewhere`,
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
return { ok: true, path: inside.path }
|
|
97
|
+
}
|
|
98
|
+
if (!isAbsolute(raw)) {
|
|
99
|
+
// A relative path is resolved against the state directory; containment is
|
|
100
|
+
// still checked so `..` cannot turn the default into an escape hatch.
|
|
101
|
+
const inside = resolveWithinRoots(candidate, [state])
|
|
102
|
+
if (inside === undefined) {
|
|
103
|
+
return { ok: false, error: `relative path escapes the plugin state directory (${state})` }
|
|
104
|
+
}
|
|
105
|
+
return { ok: true, path: inside.path }
|
|
106
|
+
}
|
|
107
|
+
return { ok: true, path: candidate }
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* Whether `target` is a SQLite database produced by this tool: it must open,
|
|
112
|
+
* carry our `user_version` marker and expose the exported `entries` schema.
|
|
113
|
+
* An arbitrary SQLite file (even with a parent directory deliberately named
|
|
114
|
+
* like an export) is refused, so `overwrite` cannot destroy user data.
|
|
115
|
+
* @param sqlite - the `node:sqlite` module.
|
|
116
|
+
* @param target - existing file to inspect.
|
|
117
|
+
*/
|
|
118
|
+
export function isOwnExportDatabase(sqlite: SqliteModuleLike, target: string): boolean {
|
|
119
|
+
let db: SqliteDatabaseLike | undefined
|
|
120
|
+
try {
|
|
121
|
+
db = new sqlite.DatabaseSync(target, { readOnly: true })
|
|
122
|
+
} catch {
|
|
123
|
+
return false
|
|
124
|
+
}
|
|
125
|
+
try {
|
|
126
|
+
const version = db.prepare('PRAGMA user_version').get()
|
|
127
|
+
const value = typeof version === 'object' && version !== null
|
|
128
|
+
? Number((version as Record<string, unknown>).user_version)
|
|
129
|
+
: Number.NaN
|
|
130
|
+
if (value !== EXPORT_DB_USER_VERSION) return false
|
|
131
|
+
// Prepares (and thereby validates) the documented schema without rows.
|
|
132
|
+
db.prepare('SELECT path, name, dir, size, mtime_ms, ext FROM entries LIMIT 0').get()
|
|
133
|
+
return true
|
|
134
|
+
} catch {
|
|
135
|
+
return false
|
|
136
|
+
} finally {
|
|
137
|
+
try {
|
|
138
|
+
db.close()
|
|
139
|
+
} catch {
|
|
140
|
+
// A read-only handle that already failed to close does not change the verdict.
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
|
|
29
145
|
/** Build the locator_export tool. */
|
|
30
146
|
export function makeExportTool(rt: LocatorRuntime) {
|
|
31
147
|
return defineTool({
|
|
@@ -35,11 +151,17 @@ export function makeExportTool(rt: LocatorRuntime) {
|
|
|
35
151
|
'',
|
|
36
152
|
'The database has one table, `entries(path TEXT PRIMARY KEY, name TEXT, dir INTEGER, size INTEGER, mtime_ms INTEGER, ext TEXT)`. It is a snapshot: run the tool again to refresh it. The index itself stays in its compact binary form; this is for external SQL tools, dashboards or scripts.',
|
|
37
153
|
'',
|
|
154
|
+
'The output path must stay inside the plugin state directory: omit `path` for `<stateDir>/locator-export.sqlite`, use a relative `path`, or pass an absolute path under the reported state directory. Set `allowOutsideStateDir: true` to export somewhere else deliberately. `overwrite` only replaces a database this tool created; any other existing file is left untouched and the call fails. Writes are atomic (temporary file + rename).',
|
|
155
|
+
'',
|
|
38
156
|
'Use it when the user asks for a queryable copy of their file index, wants to run SQL against it, or needs the data in another program. It is expensive on a million-entry index (tens of seconds and a large file), so do not call it routinely.',
|
|
39
157
|
].join('\n'),
|
|
40
158
|
parameters: {
|
|
41
|
-
path: {
|
|
42
|
-
|
|
159
|
+
path: {
|
|
160
|
+
type: 'string',
|
|
161
|
+
description: 'Output .sqlite/.db file. Defaults to <stateDir>/locator-export.sqlite; relative paths resolve inside the state directory, absolute paths must be inside it unless allowOutsideStateDir is true.',
|
|
162
|
+
},
|
|
163
|
+
overwrite: { type: 'boolean', description: 'Replace an existing file created by this tool (default false). Any other existing file is never overwritten.' },
|
|
164
|
+
allowOutsideStateDir: { type: 'boolean', description: 'Allow an absolute path outside the plugin state directory (explicit opt-in, default false).' },
|
|
43
165
|
pageSize: { type: 'integer', description: 'Rows per engine request (default 5000, max 10000).' },
|
|
44
166
|
},
|
|
45
167
|
timeoutMs: 180_000,
|
|
@@ -56,73 +178,141 @@ export function makeExportTool(rt: LocatorRuntime) {
|
|
|
56
178
|
},
|
|
57
179
|
async execute(args) {
|
|
58
180
|
const started = Date.now()
|
|
59
|
-
const target =
|
|
60
|
-
if (!
|
|
61
|
-
|
|
62
|
-
|
|
181
|
+
const target = resolveExportTarget(args.path, rt.stateDir, args.allowOutsideStateDir === true)
|
|
182
|
+
if (!target.ok) return { ok: false as const, error: target.error }
|
|
183
|
+
const output = target.path
|
|
184
|
+
const existed = existsSync(output)
|
|
185
|
+
if (existed && args.overwrite !== true) {
|
|
186
|
+
return { ok: false as const, error: `refusing to overwrite ${output}; pass overwrite: true` }
|
|
63
187
|
}
|
|
64
|
-
const pageSize = Math.min(10_000, Math.max(100, args.pageSize ?? 5000))
|
|
65
|
-
mkdirSync(dirname(target), { recursive: true })
|
|
66
188
|
|
|
67
|
-
let sqlite:
|
|
189
|
+
let sqlite: SqliteModuleLike
|
|
68
190
|
try {
|
|
69
|
-
sqlite = await import('node:sqlite')
|
|
191
|
+
sqlite = await import('node:sqlite') as unknown as SqliteModuleLike
|
|
70
192
|
} catch {
|
|
71
193
|
return { ok: false as const, error: 'node:sqlite is unavailable; Node 22.5 or newer is required' }
|
|
72
194
|
}
|
|
195
|
+
// Overwrite is a deletion: only this tool's own database may be deleted.
|
|
196
|
+
if (existed && !isOwnExportDatabase(sqlite, output)) {
|
|
197
|
+
return { ok: false as const, error: `refusing to overwrite ${output}: not a database created by locator_export` }
|
|
198
|
+
}
|
|
73
199
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
200
|
+
const pageSize = Math.min(10_000, Math.max(100, args.pageSize ?? 5000))
|
|
201
|
+
try {
|
|
202
|
+
mkdirSync(dirname(output), { recursive: true })
|
|
203
|
+
} catch (error) {
|
|
204
|
+
return { ok: false as const, error: messageOf(error) }
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
// Build in a sibling temp file so the destination is only ever the old
|
|
208
|
+
// complete database or the new complete one, never a partial write.
|
|
209
|
+
const temporary = temporaryPathFor(output)
|
|
77
210
|
let rows = 0
|
|
78
211
|
try {
|
|
79
|
-
|
|
80
|
-
db.exec('PRAGMA synchronous = OFF')
|
|
81
|
-
db.exec(`CREATE TABLE entries (
|
|
82
|
-
path TEXT PRIMARY KEY,
|
|
83
|
-
name TEXT NOT NULL,
|
|
84
|
-
dir INTEGER NOT NULL,
|
|
85
|
-
size INTEGER NOT NULL,
|
|
86
|
-
mtime_ms INTEGER NOT NULL,
|
|
87
|
-
ext TEXT NOT NULL
|
|
88
|
-
) WITHOUT ROWID`)
|
|
89
|
-
db.exec('CREATE INDEX entries_mtime ON entries(mtime_ms)')
|
|
90
|
-
const insert = db.prepare('INSERT OR REPLACE INTO entries (path, name, dir, size, mtime_ms, ext) VALUES (?, ?, ?, ?, ?, ?)')
|
|
91
|
-
db.exec('BEGIN')
|
|
92
|
-
let after = 0
|
|
93
|
-
for (;;) {
|
|
94
|
-
const page = await rt.dump(after, pageSize)
|
|
95
|
-
for (const entry of page.entries) {
|
|
96
|
-
insert.run(entry.path, entry.name, entry.dir ? 1 : 0, entry.size, entry.mtime, entry.ext)
|
|
97
|
-
rows++
|
|
98
|
-
}
|
|
99
|
-
after = page.next
|
|
100
|
-
if (page.done || page.entries.length === 0) break
|
|
101
|
-
await new Promise(resolve => setImmediate(resolve))
|
|
102
|
-
}
|
|
103
|
-
db.exec('COMMIT')
|
|
212
|
+
rows = await writeDatabase(sqlite, rt, temporary, pageSize)
|
|
104
213
|
} catch (error) {
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
rmSync(
|
|
214
|
+
rmSync(temporary, { force: true })
|
|
215
|
+
return { ok: false as const, error: messageOf(error) }
|
|
216
|
+
}
|
|
217
|
+
try {
|
|
218
|
+
replaceWithRename(sqlite, temporary, output)
|
|
219
|
+
} catch (error) {
|
|
220
|
+
rmSync(temporary, { force: true })
|
|
112
221
|
return { ok: false as const, error: messageOf(error) }
|
|
113
222
|
}
|
|
114
|
-
db.close()
|
|
115
223
|
return {
|
|
116
224
|
ok: true as const,
|
|
117
|
-
path:
|
|
225
|
+
path: output,
|
|
118
226
|
rows,
|
|
119
|
-
bytes: statSync(
|
|
227
|
+
bytes: statSync(output).size,
|
|
120
228
|
tookMs: Date.now() - started,
|
|
121
229
|
}
|
|
122
230
|
},
|
|
123
231
|
})
|
|
124
232
|
}
|
|
125
233
|
|
|
234
|
+
/** Stream the index dump into a fresh database at `temporary`; returns the row count. */
|
|
235
|
+
async function writeDatabase(
|
|
236
|
+
sqlite: SqliteModuleLike,
|
|
237
|
+
rt: LocatorRuntime,
|
|
238
|
+
temporary: string,
|
|
239
|
+
pageSize: number,
|
|
240
|
+
): Promise<number> {
|
|
241
|
+
rt.start()
|
|
242
|
+
const db = new sqlite.DatabaseSync(temporary)
|
|
243
|
+
let rows = 0
|
|
244
|
+
try {
|
|
245
|
+
db.exec('PRAGMA journal_mode = MEMORY')
|
|
246
|
+
db.exec('PRAGMA synchronous = OFF')
|
|
247
|
+
db.exec(`CREATE TABLE entries (
|
|
248
|
+
path TEXT PRIMARY KEY,
|
|
249
|
+
name TEXT NOT NULL,
|
|
250
|
+
dir INTEGER NOT NULL,
|
|
251
|
+
size INTEGER NOT NULL,
|
|
252
|
+
mtime_ms INTEGER NOT NULL,
|
|
253
|
+
ext TEXT NOT NULL
|
|
254
|
+
) WITHOUT ROWID`)
|
|
255
|
+
db.exec('CREATE INDEX entries_mtime ON entries(mtime_ms)')
|
|
256
|
+
// Ownership marker: only a database carrying it can be replaced later.
|
|
257
|
+
db.exec(`PRAGMA user_version = ${String(EXPORT_DB_USER_VERSION)}`)
|
|
258
|
+
const insert = db.prepare('INSERT OR REPLACE INTO entries (path, name, dir, size, mtime_ms, ext) VALUES (?, ?, ?, ?, ?, ?)')
|
|
259
|
+
db.exec('BEGIN')
|
|
260
|
+
let after = 0
|
|
261
|
+
for (;;) {
|
|
262
|
+
const page = await rt.dump(after, pageSize)
|
|
263
|
+
for (const entry of page.entries) {
|
|
264
|
+
insert.run(entry.path, entry.name, entry.dir ? 1 : 0, entry.size, entry.mtime, entry.ext)
|
|
265
|
+
rows++
|
|
266
|
+
}
|
|
267
|
+
after = page.next
|
|
268
|
+
if (page.done || page.entries.length === 0) break
|
|
269
|
+
await new Promise(resolve => setImmediate(resolve))
|
|
270
|
+
}
|
|
271
|
+
db.exec('COMMIT')
|
|
272
|
+
return rows
|
|
273
|
+
} catch (error) {
|
|
274
|
+
try {
|
|
275
|
+
db.exec('ROLLBACK')
|
|
276
|
+
} catch {
|
|
277
|
+
// The transaction may already be closed; the temp file is removed by the caller.
|
|
278
|
+
}
|
|
279
|
+
throw error
|
|
280
|
+
} finally {
|
|
281
|
+
try {
|
|
282
|
+
db.close()
|
|
283
|
+
} catch {
|
|
284
|
+
// Closing a failed build must not mask the real error.
|
|
285
|
+
}
|
|
286
|
+
}
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/**
|
|
290
|
+
* Move the finished temp database over the destination. POSIX `rename`
|
|
291
|
+
* replaces atomically; on Windows the replace can be refused while the old
|
|
292
|
+
* database is briefly open, in which case the (re-validated) old file is
|
|
293
|
+
* removed first. The destination is never removed unless it is still a
|
|
294
|
+
* database this tool created.
|
|
295
|
+
*/
|
|
296
|
+
function replaceWithRename(sqlite: SqliteModuleLike, temporary: string, output: string): void {
|
|
297
|
+
try {
|
|
298
|
+
renameSync(temporary, output)
|
|
299
|
+
return
|
|
300
|
+
} catch (error) {
|
|
301
|
+
if (!existsSync(output)) throw error
|
|
302
|
+
if (!isOwnExportDatabase(sqlite, output)) {
|
|
303
|
+
throw new Error(`refusing to replace ${output}: it is no longer a database created by locator_export`)
|
|
304
|
+
}
|
|
305
|
+
rmSync(output, { force: true })
|
|
306
|
+
renameSync(temporary, output)
|
|
307
|
+
}
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
/** A unique sibling temp path; never a path derived from user input components. */
|
|
311
|
+
function temporaryPathFor(target: string): string {
|
|
312
|
+
const random = Math.random().toString(36).slice(2, 10)
|
|
313
|
+
return join(dirname(target), `.${basename(target)}.${String(process.pid)}.${Date.now().toString(36)}.${random}.tmp`)
|
|
314
|
+
}
|
|
315
|
+
|
|
126
316
|
function messageOf(error: unknown): string {
|
|
127
317
|
return error instanceof Error ? error.message : String(error)
|
|
128
318
|
}
|
package/src/find.ts
CHANGED
|
@@ -5,6 +5,7 @@
|
|
|
5
5
|
|
|
6
6
|
import { defineTool } from '@deepseek-ai/dsh-tools'
|
|
7
7
|
import type { ContentIndex, ContentState } from './content.ts'
|
|
8
|
+
import type { ContentSearchOptions } from './content-search.ts'
|
|
8
9
|
|
|
9
10
|
const HIT = {
|
|
10
11
|
type: 'object',
|
|
@@ -17,10 +18,26 @@ const HIT = {
|
|
|
17
18
|
sessionId: { type: 'string' },
|
|
18
19
|
messageId: { type: 'string' },
|
|
19
20
|
nodeKey: { type: 'string' },
|
|
21
|
+
line: { type: 'integer', description: '1-based line of the first match in the stored body (file hits).' },
|
|
20
22
|
score: { type: 'number' },
|
|
21
23
|
},
|
|
22
24
|
} as const
|
|
23
25
|
|
|
26
|
+
const STATE = {
|
|
27
|
+
type: 'object',
|
|
28
|
+
additionalProperties: false,
|
|
29
|
+
properties: {
|
|
30
|
+
building: { type: 'boolean' },
|
|
31
|
+
files: { type: 'integer' },
|
|
32
|
+
sessions: { type: 'integer' },
|
|
33
|
+
messages: { type: 'integer' },
|
|
34
|
+
truncated: { type: 'boolean' },
|
|
35
|
+
updatedAt: { type: 'integer' },
|
|
36
|
+
error: { type: 'string' },
|
|
37
|
+
warnings: { type: 'array', items: { type: 'string' }, description: 'Non-fatal build problems, e.g. an unreadable session log.' },
|
|
38
|
+
},
|
|
39
|
+
} as const
|
|
40
|
+
|
|
24
41
|
/** Build the locator_find tool. */
|
|
25
42
|
export function makeFindTool(content: ContentIndex, ensure?: () => void) {
|
|
26
43
|
return defineTool({
|
|
@@ -30,11 +47,19 @@ export function makeFindTool(content: ContentIndex, ensure?: () => void) {
|
|
|
30
47
|
'',
|
|
31
48
|
'Use it when the user remembers a phrase, a sentence, a decision or a code snippet rather than a file name. `locator_search` searches names and paths; this searches bodies and returns snippets plus `sessionId`/`messageId` for session hits, so the result can be opened at its source.',
|
|
32
49
|
'',
|
|
33
|
-
'Content is
|
|
50
|
+
'Content is substring search over an FTS5 trigram index: every term must be at least 3 characters (shorter queries are rejected with `content-query-too-short` instead of scanning the whole corpus). Text files are capped by `contentMaxFileBytes`; session logs are decompressed from `$DSH_HOME/sessions`.',
|
|
34
51
|
].join('\n'),
|
|
35
52
|
parameters: {
|
|
36
53
|
query: { type: 'string', required: true, description: 'Words or a phrase to find in file/session content.' },
|
|
37
54
|
limit: { type: 'integer', description: 'Maximum hits (default 30, at most 100).' },
|
|
55
|
+
matchMode: { type: 'string', enum: ['normal', 'extended'], description: 'normal: whitespace-separated substring terms. extended: one literal phrase with Notepad++ escapes (\\n, \\r, \\t, \\0, \\xNN, \\\\).' },
|
|
56
|
+
caseSensitive: { type: 'boolean', description: 'Match letter case exactly.' },
|
|
57
|
+
wholeWord: { type: 'boolean', description: 'Only match whole words ([A-Za-z0-9_] boundaries; CJK counts as non-word).' },
|
|
58
|
+
sessionId: { type: 'string', description: 'Only search messages of one DSH session id (defaults to the caller session in workspace scope).' },
|
|
59
|
+
scope: { type: 'string', enum: ['workspace', 'all'], description: 'workspace (default) restricts file hits to the caller workspace/cwd and session hits to the caller session; all searches every indexed file and session (explicit cross-workspace access).' },
|
|
60
|
+
count: { type: 'string', enum: ['exact', 'bounded', 'none'], description: 'How much counting work to spend; bounded stops at countLimit.' },
|
|
61
|
+
countLimit: { type: 'integer', description: 'Counting cap for bounded counts (default 1000, at most 5000).' },
|
|
62
|
+
pathPrefix: { type: 'string', description: 'Only return file hits whose path starts with this directory (session hits are unaffected).' },
|
|
38
63
|
},
|
|
39
64
|
output: {
|
|
40
65
|
schema: {
|
|
@@ -44,40 +69,82 @@ export function makeFindTool(content: ContentIndex, ensure?: () => void) {
|
|
|
44
69
|
ok: { type: 'boolean', required: true },
|
|
45
70
|
query: { type: 'string' },
|
|
46
71
|
hits: { type: 'array', items: HIT },
|
|
47
|
-
|
|
72
|
+
count: {
|
|
48
73
|
type: 'object',
|
|
49
74
|
additionalProperties: false,
|
|
50
75
|
properties: {
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
messages: { type: 'integer' },
|
|
55
|
-
truncated: { type: 'boolean' },
|
|
56
|
-
updatedAt: { type: 'integer' },
|
|
57
|
-
error: { type: 'string' },
|
|
76
|
+
value: { type: 'integer' },
|
|
77
|
+
kind: { type: 'string', enum: ['exact', 'bounded', 'unknown'] },
|
|
78
|
+
limit: { type: 'integer' },
|
|
58
79
|
},
|
|
59
80
|
},
|
|
81
|
+
warnings: { type: 'array', items: { type: 'string' } },
|
|
82
|
+
state: STATE,
|
|
60
83
|
error: { type: 'string' },
|
|
61
84
|
},
|
|
62
85
|
},
|
|
63
86
|
render: (_args, value) => {
|
|
64
|
-
const v = value as {
|
|
65
|
-
|
|
66
|
-
|
|
87
|
+
const v = value as {
|
|
88
|
+
ok: boolean
|
|
89
|
+
hits?: Array<{ kind: string; title?: string; snippet?: string; path?: string; line?: number; sessionId?: string; messageId?: string }>
|
|
90
|
+
count?: { value: number; kind: 'exact' | 'bounded' | 'unknown' }
|
|
91
|
+
warnings?: string[]
|
|
92
|
+
error?: string
|
|
93
|
+
state?: ContentState
|
|
94
|
+
}
|
|
95
|
+
if (!v.ok) {
|
|
96
|
+
const detail = v.warnings !== undefined && v.warnings.length > 0 ? ` (${[...new Set(v.warnings)].join(', ')})` : ''
|
|
97
|
+
return [{ type: 'text', text: `locator_find failed: ${v.error ?? 'unknown'}${detail}` }]
|
|
98
|
+
}
|
|
99
|
+
const lines = (v.hits ?? []).map((hit, index) => {
|
|
100
|
+
const ref = hit.kind === 'session' && (hit.sessionId !== undefined || hit.messageId !== undefined)
|
|
101
|
+
? `\n session ${String(hit.sessionId ?? '')}${hit.messageId === undefined ? '' : ` message ${String(hit.messageId)}`}`
|
|
102
|
+
: ''
|
|
103
|
+
return `${String(index + 1)}. [${hit.kind}] ${hit.title ?? ''} — ${hit.snippet ?? ''}\n ${hit.path ?? ''}${typeof hit.line === 'number' ? ` (line ${String(hit.line)})` : ''}${ref}`
|
|
104
|
+
})
|
|
105
|
+
const count = v.count === undefined
|
|
106
|
+
? ''
|
|
107
|
+
: v.count.kind === 'bounded'
|
|
108
|
+
? `, count ≥ ${String(v.count.value)}`
|
|
109
|
+
: v.count.kind === 'exact'
|
|
110
|
+
? `, count ${String(v.count.value)}`
|
|
111
|
+
: ''
|
|
112
|
+
const warnings = [...new Set([...(v.warnings ?? []), ...(v.state?.warnings ?? [])])]
|
|
67
113
|
const notes = [
|
|
68
114
|
v.state?.building ? ' (index still building)' : '',
|
|
69
115
|
v.state?.truncated === true ? ' (content budget reached: raise contentMaxTotalBytes or trim contentExcludes; later files are not searchable)' : '',
|
|
116
|
+
warnings.length > 0 ? ` (warnings: ${warnings.join(', ')})` : '',
|
|
70
117
|
].join('')
|
|
71
|
-
return [{ type: 'text', text: `${String(v.hits?.length ?? 0)} content hit(s)${notes}\n${lines.join('\n')}` }]
|
|
118
|
+
return [{ type: 'text', text: `${String(v.hits?.length ?? 0)} content hit(s)${count}${notes}\n${lines.join('\n')}` }]
|
|
72
119
|
},
|
|
73
120
|
},
|
|
74
|
-
async execute(args) {
|
|
121
|
+
async execute(args, exec) {
|
|
75
122
|
ensure?.()
|
|
76
123
|
const query = args.query.trim()
|
|
77
124
|
if (query === '') return { ok: false as const, error: 'query is empty' }
|
|
78
125
|
const limit = Math.max(1, Math.min(100, args.limit ?? 30))
|
|
79
|
-
const
|
|
80
|
-
|
|
126
|
+
const scope = args.scope === 'all' ? 'all' : 'workspace'
|
|
127
|
+
const callerSessionId = scope === 'workspace' ? exec?.agent?.session?.id : undefined
|
|
128
|
+
const callerCwd = scope === 'workspace' ? exec?.agent?.session?.header?.cwd : undefined
|
|
129
|
+
const options: ContentSearchOptions = {
|
|
130
|
+
...(args.matchMode === undefined ? {} : { matchMode: args.matchMode }),
|
|
131
|
+
...(args.caseSensitive === undefined ? {} : { caseSensitive: args.caseSensitive }),
|
|
132
|
+
...(args.wholeWord === undefined ? {} : { wholeWord: args.wholeWord }),
|
|
133
|
+
...(args.sessionId !== undefined && args.sessionId !== ''
|
|
134
|
+
? { sessionId: args.sessionId }
|
|
135
|
+
: callerSessionId === undefined ? {} : { sessionId: String(callerSessionId) }),
|
|
136
|
+
...(args.count === undefined ? {} : { count: args.count }),
|
|
137
|
+
...(args.countLimit === undefined ? {} : { countLimit: args.countLimit }),
|
|
138
|
+
...(args.pathPrefix !== undefined && args.pathPrefix !== ''
|
|
139
|
+
? { pathPrefix: args.pathPrefix }
|
|
140
|
+
: callerCwd === undefined ? {} : { pathPrefix: callerCwd }),
|
|
141
|
+
}
|
|
142
|
+
const result = await content.search(query, limit, options)
|
|
143
|
+
const state = content.status()
|
|
144
|
+
if (result.error !== undefined) {
|
|
145
|
+
return { ok: false as const, query, error: result.error, warnings: result.warnings, hits: [], state }
|
|
146
|
+
}
|
|
147
|
+
return { ok: true as const, query, hits: result.hits, count: result.count, warnings: result.warnings, state }
|
|
81
148
|
},
|
|
82
149
|
})
|
|
83
150
|
}
|