@fishdivinity/dsh-local-search 0.1.0 → 0.2.1

package/lib/format.js

@@ -1,92 +1,101 @@
-/**
- * Model-facing formatting. Results stay bounded: callers cap items and text
- * before these functions run.
- */
-
-/** Convert a Windows FILETIME (100 ns ticks since 1601) to an ISO string. */
-export function filetimeToIso(ft) {
-  if (typeof ft !== 'number' || ft <= 0) return undefined
-  const date = new Date(ft / 10000 - 11644473600000)
-  return Number.isNaN(date.getTime()) ? undefined : date.toISOString()
-}
-
-function sizeSuffix(size) {
-  return typeof size === 'number' && Number.isFinite(size) ? `\t${size} B` : ''
-}
-
-function modifiedSuffix(modified) {
-  return typeof modified === 'string' && modified.length > 0 ? `\t${modified}` : ''
-}
-
-/** Format the files result (Everything). */
-export function formatFiles(value) {
-  const items = Array.isArray(value.items) ? value.items : []
-  if (items.length === 0) return 'No files found.'
-  const header = value.truncated
-    ? `Found ${items.length} path(s) (capped)`
-    : `Found ${items.length} path(s)`
-  const body = items
-    .map((item) => `${item.path}${sizeSuffix(item.size)}${modifiedSuffix(item.modified)}`)
-    .join('\n')
-  return `${header}\n\n${body}`
-}
-
-/** Format the content result (Anytxt). */
-export function formatContent(value) {
-  const items = Array.isArray(value.items) ? value.items : []
-  if (items.length === 0) return `No content matches (indexed total ${value.total ?? 0}).`
-  const header = `${items.length} of ${value.total ?? items.length} indexed file(s) match`
-  const body = items.map((item) => `${item.ref}\t${item.path}`).join('\n')
-  const footer = value.truncated ? '\n\n(Showing the first results; narrow the query or raise limit to see more.)' : ''
-  return `${header}\n\n${body}${footer}`
-}
-
-/** Format fragments from one indexed document. */
-export function formatFragments(value) {
-  const fragments = Array.isArray(value.fragments) ? value.fragments.filter(Boolean) : []
-  return fragments.length > 0 ? fragments.join('\n---\n') : 'No fragments returned.'
-}
-
-/** Format a document excerpt with its total length. */
-export function formatRead(value) {
-  const total = typeof value.totalChars === 'number' ? value.totalChars : 0
-  const offset = typeof value.offset === 'number' ? value.offset : 0
-  const returned = typeof value.returned === 'number' ? value.returned : 0
-  return `chars ${total}; showing ${offset}..${offset + returned}\n\n${value.text ?? ''}`
-}
-
-/** Format both engine statuses and the configured roots. */
-export function formatStatus(value) {
-  const lines = []
-  const everything = value.everything ?? {}
-  if (everything.ok) {
-    lines.push(
-      `Everything: OK${everything.version ? ` (${everything.version})` : ''}${everything.path ? ` via ${everything.path}` : ''}`,
-    )
-  } else if (everything.code === 'SKIPPED') {
-    lines.push(`Everything: SKIPPED${everything.message ? ` — ${everything.message}` : ''}`)
-  } else {
-    lines.push(
-      `Everything: DOWN — ${everything.code ?? 'UNKNOWN'}${everything.message ? `: ${everything.message}` : ''}`,
-    )
-  }
-  const anytxt = value.anytxt ?? {}
-  if (anytxt.ok) {
-    lines.push(`Anytxt: OK${anytxt.url ? ` at ${anytxt.url}` : ''}`)
-  } else if (anytxt.code === 'SKIPPED') {
-    lines.push(`Anytxt: SKIPPED${anytxt.message ? ` — ${anytxt.message}` : ''}`)
-  } else {
-    lines.push(
-      `Anytxt: DOWN — ${anytxt.code ?? 'UNKNOWN'}${anytxt.message ? `: ${anytxt.message}` : ''}`,
-    )
-  }
-  const roots = value.roots ?? {}
-  lines.push(`workspace=${roots.workspace ?? ''}`)
-  lines.push(`work=${roots.work ?? ''}`)
-  lines.push(`personal=${roots.personal ?? ''}`)
-  lines.push(`all=${Array.isArray(roots.all) ? roots.all.join(',') : ''}`)
-  if (value.engines) {
-    lines.push(`engines=files:${(value.engines.files ?? []).join(',')} content:${(value.engines.content ?? []).join(',')}`)
-  }
-  return lines.join('\n')
-}
+/**
+ * Model-facing formatting. Results stay bounded: callers cap items and text
+ * before these functions run.
+ */
+
+/** Convert a Windows FILETIME (100 ns ticks since 1601) to an ISO string. */
+export function filetimeToIso(ft) {
+  if (typeof ft !== 'number' || ft <= 0) return undefined
+  const date = new Date(ft / 10000 - 11644473600000)
+  return Number.isNaN(date.getTime()) ? undefined : date.toISOString()
+}
+
+function sizeSuffix(size) {
+  return typeof size === 'number' && Number.isFinite(size) ? `\t${size} B` : ''
+}
+
+function modifiedSuffix(modified) {
+  return typeof modified === 'string' && modified.length > 0 ? `\t${modified}` : ''
+}
+
+/** Format the files result (Everything). */
+export function formatFiles(value) {
+  const items = Array.isArray(value.items) ? value.items : []
+  if (items.length === 0) {
+    // The cap is applied before the index filter, so an empty window can still
+    // mean "more existed": say so instead of a flat "no files found".
+    return value.truncated
+      ? 'No files found in the returned window (the result set was capped; narrow the query).'
+      : 'No files found.'
+  }
+  const header = value.truncated
+    ? `Found ${items.length} path(s) (capped)`
+    : `Found ${items.length} path(s)`
+  const body = items
+    .map((item) => `${item.path}${sizeSuffix(item.size)}${modifiedSuffix(item.modified)}`)
+    .join('\n')
+  return `${header}\n\n${body}`
+}
+
+/** Format the content result (Anytxt). */
+export function formatContent(value) {
+  const items = Array.isArray(value.items) ? value.items : []
+  if (items.length === 0) return `No content matches (indexed total ${value.total ?? 0}).`
+  const header = `${items.length} of ${value.total ?? items.length} indexed file(s) match`
+  const body = items.map((item) => `${item.ref}\t${item.path}`).join('\n')
+  const footer = value.truncated ? '\n\n(Showing the first results; narrow the query or raise limit to see more.)' : ''
+  return `${header}\n\n${body}${footer}`
+}
+
+/** Format fragments from one indexed document. */
+export function formatFragments(value) {
+  const fragments = Array.isArray(value.fragments) ? value.fragments.filter(Boolean) : []
+  return fragments.length > 0 ? fragments.join('\n---\n') : 'No fragments returned.'
+}
+
+/** Format a document excerpt with its total length. */
+export function formatRead(value) {
+  const total = typeof value.totalChars === 'number' ? value.totalChars : 0
+  const offset = typeof value.offset === 'number' ? value.offset : 0
+  const returned = typeof value.returned === 'number' ? value.returned : 0
+  if (returned === 0) return `chars ${total}; nothing to show at offset ${offset}`
+  // The end is inclusive so a reader can subtract the two numbers directly.
+  return `chars ${total}; showing ${offset}..${offset + returned - 1}\n\n${value.text ?? ''}`
+}
+
+/**
+ * One engine's status line.
+ *
+ * An aborted probe means this call was cancelled, not that the index is down —
+ * reporting it as DOWN sends the reader after the wrong problem.
+ * @param {string} label - engine label
+ * @param {object} status - the probe result
+ * @param {(status: object) => string} okDetail - the suffix a healthy engine adds
+ * @returns {string} the line
+ */
+function engineLine(label, status, okDetail) {
+  if (status.ok) return `${label}: OK${okDetail(status)}`
+  if (status.code === 'SKIPPED') return `${label}: SKIPPED${status.message ? ` — ${status.message}` : ''}`
+  if (typeof status.code === 'string' && status.code.endsWith('_ABORTED')) {
+    return `${label}: ABORTED — ${status.code}`
+  }
+  return `${label}: DOWN — ${status.code ?? 'UNKNOWN'}${status.message ? `: ${status.message}` : ''}`
+}
+
+/** Format both engine statuses and the configured roots. */
+export function formatStatus(value) {
+  const lines = [
+    engineLine('Everything', value.everything ?? {}, (status) =>
+      `${status.version ? ` (${status.version})` : ''}${status.path ? ` via ${status.path}` : ''}`),
+    engineLine('Anytxt', value.anytxt ?? {}, (status) => (status.url ? ` at ${status.url}` : '')),
+  ]
+  const roots = value.roots ?? {}
+  lines.push(`workspace=${roots.workspace ?? ''}`)
+  lines.push(`work=${roots.work ?? ''}`)
+  lines.push(`personal=${roots.personal ?? ''}`)
+  lines.push(`all=${Array.isArray(roots.all) ? roots.all.join(',') : ''}`)
+  if (value.engines) {
+    lines.push(`engines=files:${(value.engines.files ?? []).join(',')} content:${(value.engines.content ?? []).join(',')}`)
+  }
+  return lines.join('\n')
+}

package/lib/index.js

@@ -1,71 +1,77 @@
-import z from '@deepseek-ai/schemastery'
-import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
-import { createTools } from './tools.js'
-
-/** Cordis plugin name used by loader diagnostics. */
-export const name = 'local-search'
-
-/** Services required by the tools. */
-export const inject = ['tools', 'systemPrompt', 'workingDirectory']
-
-export const Config = z.object({
-  esPath: z.string().default('').description('Absolute path to es.exe; empty auto-detects PATH and common install folders.'),
-  anytxtUrl: z.string().default('http://127.0.0.1:9920').description('Local Anytxt JSON-RPC endpoint; :9921 is tried as a fallback.'),
-  workspaceRoot: z.string().default('').description('Root for scope=workspace; empty uses the session working directory.'),
-  workRoot: z.string().default('').description('Root for scope=work; required before using that scope.'),
-  personalRoot: z.string().default('').description('Root for scope=personal; required before using that scope.'),
-  allRoots: z.string().default('').description('Semicolon-separated roots for Anytxt scope=all; empty uses C: and D: when present.'),
-  maxResults: z.number().default(20).description('Default result cap; the hard cap is 100.'),
-  timeoutMs: z.number().default(30000).description('Per-call timeout budget in milliseconds.'),
-  readMaxChars: z.number().default(8000).description('Default local_search_read window; the hard cap is 20,000 characters.'),
-  esEncoding: z.string().default('gbk').description('Code page used to decode es.exe output; zh-CN uses gbk.'),
-})
-
-function assertPositiveInteger(field, value) {
-  if (!Number.isInteger(value) || value < 1) {
-    throw new Error(`dsh-local-search: ${field} must be a positive integer`)
-  }
-}
-
-/**
- * Validate a candidate config. Shared by activation and the future config
- * page's save/test path; the loader may pass a fresh object on HMR.
- */
-export function validateConfig(config) {
-  assertPositiveInteger('maxResults', config.maxResults)
-  assertPositiveInteger('timeoutMs', config.timeoutMs)
-  assertPositiveInteger('readMaxChars', config.readMaxChars)
-  if (config.timeoutMs > MAX_TIMER_DELAY_MS) {
-    throw new Error(`dsh-local-search: timeoutMs must be no greater than ${MAX_TIMER_DELAY_MS}`)
-  }
-  if (!/^https?:\/\//i.test(config.anytxtUrl)) {
-    throw new Error('dsh-local-search: anytxtUrl must start with http:// or https://')
-  }
-  return config
-}
-
-/**
- * Register the five local-search tools and their routing guidance.
- */
-export async function apply(ctx, config) {
-  validateConfig(config)
-
-  ctx.effect(() => {
-    const disposers = createTools(ctx, config).map((tool) => ctx.tools.register(tool))
-    return () => {
-      for (const dispose of disposers) dispose()
-    }
-  })
-
-  ctx.effect(() =>
-    ctx.systemPrompt.section({
-      name: 'tool:local_search',
-      order: 106,
-      text:
-        'Use local_search_files for file/folder names or paths, especially outside the workspace or across drives. ' +
-        'Use local_search_content for text inside PDF/Office/EPUB/TXT/MD documents or a whole-disk content search, then local_search_fragments or local_search_read for detail. ' +
-        'Keep grep/glob for source code and plain text already in the workspace. ' +
-        'If a search reports EVERYTHING_DOWN or ANYTXT_DOWN, fall back to grep/glob and say that you fell back.',
-    }),
-  )
-}
+import z from '@deepseek-ai/schemastery'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import { createTools } from './tools.js'
+import { validateConfig } from './config.js'
+import { registerStatusRoute } from './route.js'
+import { MAX_LIMIT, MAX_READ } from './limits.js'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'local-search'
+
+/** Services required by the tools. */
+export const inject = ['tools', 'systemPrompt', 'workingDirectory']
+
+// Every field the Plugins page edits is volatile: that is what makes the
+// settings namespace served and a page write accepted. timeoutMs stays a
+// fixed number because tool registration captures it (see lib/config.js).
+// esEncoding stays a plain string on purpose: 0.1 accepted any label and fell
+// back to UTF-8 in `decodeEs`, so narrowing it to a union would refuse to
+// activate a profile that worked yesterday. The page offers the two labels
+// that matter; YAML keeps the old tolerance.
+export const Config = z.object({
+  esPath: z.string().default('').volatile().description('Absolute path to es.exe; empty auto-detects PATH and common install folders.'),
+  anytxtUrl: z.string().default('http://127.0.0.1:9920').volatile().description('Local Anytxt JSON-RPC endpoint on this machine (127.0.0.1, localhost or [::1]); :9921 is tried as a fallback.'),
+  workspaceRoot: z.string().default('').volatile().description('Root for scope=workspace; empty uses the session working directory.'),
+  workRoot: z.string().default('').volatile().description('Root for scope=work; required before using that scope.'),
+  personalRoot: z.string().default('').volatile().description('Root for scope=personal; required before using that scope.'),
+  allRoots: z.string().default('').volatile().description('Semicolon-separated roots for Anytxt scope=all; empty uses C: and D: when present.'),
+  maxResults: z.number().min(1).max(MAX_LIMIT).default(20).volatile().description(`Default result cap; the hard cap is ${MAX_LIMIT}.`),
+  timeoutMs: z.number().default(30000).description('Per-call timeout budget in milliseconds; profile YAML only, because each tool fixes its deadline at registration.'),
+  readMaxChars: z.number().min(1).max(MAX_READ).default(8000).volatile().description(`Default local_search_read window; the hard cap is ${MAX_READ} characters.`),
+  esEncoding: z.string().default('gbk').volatile().description('Code page used to decode es.exe output: gbk for a zh-CN console, utf-8 otherwise. Any TextDecoder label is accepted; the page offers these two.'),
+})
+
+export { validateConfig }
+
+/**
+ * Register the five local-search tools, their routing guidance, and the
+ * configuration page's probe route.
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {object} config - schema output; volatile fields are live references
+ */
+export async function apply(ctx, config) {
+  validateConfig(config, MAX_TIMER_DELAY_MS)
+
+  ctx.effect(() => {
+    const disposers = createTools(ctx, config).map((tool) => ctx.tools.register(tool))
+    return () => {
+      for (const dispose of disposers) dispose()
+    }
+  })
+
+  // Routing hint, not a tool catalogue: each tool description already says what
+  // it is for, so this only orders the choice and names the fallback. Four
+  // clauses, ~250 characters — half the previous text for the same decision.
+  ctx.effect(() =>
+    ctx.systemPrompt.section({
+      name: 'tool:local_search',
+      order: 106,
+      text:
+        'Names anywhere outside the workspace: local_search_files. ' +
+        'Document text (PDF/Office/EPUB, whole disk): local_search_content, then fragments/read. ' +
+        'Workspace code and text: grep/glob. ' +
+        'On *_DOWN, fall back to grep/glob and say so.',
+    }),
+  )
+
+  // The configuration page's Test control: the browser cannot call the local
+  // Anytxt JSON-RPC itself, so the Host answers for it. A deployment without a
+  // web server simply has no Test control and no route.
+  ctx.inject(['webServer'], (webCtx) => {
+    const server = webCtx.get('webServer')
+    webCtx.effect(
+      () => registerStatusRoute(server, config),
+      'local-search: configuration page probe route',
+    )
+  })
+}

package/lib/limits.js

@@ -0,0 +1,14 @@
+/**
+ * The hard caps one call may ask for.
+ *
+ * The schema caps the saved default, the tools clamp a per-call argument, and
+ * the configuration page mirrors the same numbers so a save cannot be rejected.
+ * They live here to stay one value; the page cannot import this file (a classic
+ * script has no ESM imports), so its copy is checked by a test instead.
+ */
+
+/** Hard cap on a result count. */
+export const MAX_LIMIT = 100
+
+/** Hard cap on characters one read returns. */
+export const MAX_READ = 20000

package/lib/probe.js

@@ -0,0 +1,88 @@
+/**
+ * One probe of both local indexes, shared by the model-facing
+ * `local_search_status` tool and the configuration page's Test control.
+ *
+ * They answer the same question — "can this machine reach its indexes right
+ * now?" — so they must not drift into two slightly different probes. The
+ * probe goes through the engine registry, so a new backend is still one entry
+ * in `lib/engines.js`.
+ */
+
+import { readConfig } from './config.js'
+import { resolveContentEngine, resolveFilesEngine } from './engines.js'
+import { everythingInstalled } from './everything.js'
+
+/**
+ * Which link of the Everything chain is missing.
+ *
+ * This detail is for the person reading the configuration page, who can install
+ * or start something; the model keeps the two stable codes. When the install
+ * check itself could not run, the answer is `unknown` and the page falls back to
+ * its generic hint rather than telling someone to install what they already have.
+ * @param {string} code - the error code the probe produced
+ * @returns {'not-installed'|'not-running'|'es-missing'|'unknown'} the actionable cause
+ */
+export function diagnoseEverything(code, presence = everythingInstalled()) {
+  if (!presence.known) return 'unknown'
+  if (!presence.installed) return 'not-installed'
+  return code === 'EVERYTHING_ES_NOT_FOUND' ? 'es-missing' : 'not-running'
+}
+
+/**
+ * Probe the configured indexes once, never throwing.
+ * @param {object} config - schema output, volatile references included
+ * @param {object} [options]
+ * @param {string} [options.only] - `auto` probes both; `anytxt` / `everything` skips the other
+ * @param {string} [options.workspace] - root Anytxt is asked about
+ * @param {string} [options.anytxtUrl] - endpoint to probe instead of the saved one (a page draft)
+ * @param {boolean} [options.detail] - add the page-facing cause to a failed engine
+ * @param {AbortSignal} [options.signal] - caller cancellation
+ * @returns {Promise<{everything: object, anytxt: object}>} both statuses
+ */
+export async function probeEngines(config, { only = 'auto', workspace, anytxtUrl, signal, detail = false } = {}) {
+  const cfg = readConfig(config)
+  const everything = { ok: false }
+  const anytxt = { ok: false }
+  const budget = Number.isFinite(cfg.timeoutMs) ? cfg.timeoutMs : 5000
+  // A probe is a diagnostic, not a search: it gets a floor as well as a ceiling,
+  // because a tiny timeoutMs would report a healthy engine as DOWN.
+  const probeBudget = Math.max(1500, Math.min(budget, 5000))
+
+  if (only !== 'anytxt') {
+    try {
+      Object.assign(everything, await resolveFilesEngine('everything').status({
+        config: cfg,
+        esPath: cfg.esPath,
+        timeoutMs: probeBudget,
+        signal,
+        encoding: cfg.esEncoding,
+      }))
+    } catch (error) {
+      everything.code = error.code || 'EVERYTHING_DOWN'
+      everything.message = error.message
+      if (detail && everything.code !== 'EVERYTHING_ABORTED') everything.detail = diagnoseEverything(everything.code)
+    }
+  } else {
+    everything.code = 'SKIPPED'
+    everything.message = 'not checked because engine=anytxt'
+  }
+
+  if (only !== 'everything') {
+    try {
+      Object.assign(anytxt, await resolveContentEngine('anytxt').status({
+        url: anytxtUrl || cfg.anytxtUrl,
+        root: workspace || cfg.workspaceRoot || process.cwd(),
+        timeoutMs: probeBudget,
+        signal,
+      }))
+    } catch (error) {
+      anytxt.code = error.code || 'ANYTXT_DOWN'
+      anytxt.message = error.message
+    }
+  } else {
+    anytxt.code = 'SKIPPED'
+    anytxt.message = 'not checked because engine=everything'
+  }
+
+  return { everything, anytxt }
+}

package/lib/ref.js

@@ -1,38 +1,38 @@
-import { EngineError } from './errors.js'
-
-/**
- * Refs are self-describing: `<engine>:<id>`. This keeps a Recoll docid, an
- * Everything fid, and a future Windows Search item from colliding when the
- * model passes a stale ref back to local_search_read/local_search_fragments.
- */
-export function formatRef(engine, id) {
-  if (!engine || typeof engine !== 'string') {
-    throw new EngineError('engine name is required to format a ref', 'INVALID_REF')
-  }
-  if (id === undefined || id === null || String(id).length === 0) {
-    throw new EngineError('ref id is required', 'INVALID_REF')
-  }
-  return `${engine}:${String(id)}`
-}
-
-/** Parse `<engine>:<id>`; reject bare ids with an actionable hint. */
-export function parseRef(ref) {
-  const text = String(ref ?? '')
-  const separator = text.indexOf(':')
-  if (separator <= 0 || separator === text.length - 1) {
-    throw new EngineError(`ref must look like "<engine>:<id>", got "${text}"`, 'INVALID_REF', {
-      hint: 'Rerun local_search_content and pass the item ref unchanged.',
-    })
-  }
-  return { engine: text.slice(0, separator), id: text.slice(separator + 1) }
-}
-
-/** Ensure a ref belongs to the resolved engine. */
-export function assertRefEngine(parsed, engineName) {
-  if (parsed.engine !== engineName) {
-    throw new EngineError(`ref belongs to ${parsed.engine}, not ${engineName}`, 'INVALID_REF', {
-      hint: 'Pass the item ref and its engine together, unchanged.',
-    })
-  }
-  return parsed
-}
+import { EngineError } from './errors.js'
+
+/**
+ * Refs are self-describing: `<engine>:<id>`. This keeps a Recoll docid, an
+ * Everything fid, and a future Windows Search item from colliding when the
+ * model passes a stale ref back to local_search_read/local_search_fragments.
+ */
+export function formatRef(engine, id) {
+  if (!engine || typeof engine !== 'string') {
+    throw new EngineError('engine name is required to format a ref', 'INVALID_REF')
+  }
+  if (id === undefined || id === null || String(id).length === 0) {
+    throw new EngineError('ref id is required', 'INVALID_REF')
+  }
+  return `${engine}:${String(id)}`
+}
+
+/** Parse `<engine>:<id>`; reject bare ids with an actionable hint. */
+export function parseRef(ref) {
+  const text = String(ref ?? '')
+  const separator = text.indexOf(':')
+  if (separator <= 0 || separator === text.length - 1) {
+    throw new EngineError(`ref must look like "<engine>:<id>", got "${text}"`, 'INVALID_REF', {
+      hint: 'Rerun local_search_content and pass the item ref unchanged.',
+    })
+  }
+  return { engine: text.slice(0, separator), id: text.slice(separator + 1) }
+}
+
+/** Ensure a ref belongs to the resolved engine. */
+export function assertRefEngine(parsed, engineName) {
+  if (parsed.engine !== engineName) {
+    throw new EngineError(`ref belongs to ${parsed.engine}, not ${engineName}`, 'INVALID_REF', {
+      hint: 'Pass the item ref and its engine together, unchanged.',
+    })
+  }
+  return parsed
+}