@fishdivinity/dsh-local-search 0.2.0 → 0.3.0

package/lib/format.js

@@ -1,9 +1,8 @@
 /**
- * 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. */
+/** 把 Windows FILETIME（1601 起的 100ns 计数）转成 ISO 字符串。 */
 export function filetimeToIso(ft) {
   if (typeof ft !== 'number' || ft <= 0) return undefined
   const date = new Date(ft / 10000 - 11644473600000)
@@ -18,10 +17,16 @@ function modifiedSuffix(modified) {
   return typeof modified === 'string' && modified.length > 0 ? `\t${modified}` : ''
 }
 
-/** Format the files result (Everything). */
+/** 格式化文件名结果（Everything）。 */
 export function formatFiles(value) {
   const items = Array.isArray(value.items) ? value.items : []
-  if (items.length === 0) return 'No files found.'
+  if (items.length === 0) {
+    // 上限先于排除过滤生效，所以空窗口仍可能意味着「本来还有更多」：要说清楚，而不是干巴巴
+    // 一句 "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)`
@@ -31,7 +36,7 @@ export function formatFiles(value) {
   return `${header}\n\n${body}`
 }
 
-/** Format the content result (Anytxt). */
+/** 格式化内容结果（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}).`
@@ -41,47 +46,47 @@ export function formatContent(value) {
   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 ?? ''}`
 }
 
-/** 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}` : ''}`,
-    )
+/**
+ * 一个引擎的状态行。
+ *
+ * 探测被取消说明这次调用被中止了，不是索引挂了——报成 DOWN 会让人去查错的问题。
+ * @param {string} label - 引擎标签
+ * @param {object} status - 探测结果
+ * @param {(status: object) => string} okDetail - 引擎正常时追加的后缀
+ * @returns {string} 这一行
+ */
+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}` : ''}`
+}
+
+/** 格式化两个引擎的状态与配置的根。 */
+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 ?? ''}`)

package/lib/index.js

@@ -1,46 +1,73 @@
-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 { Config } from './schema.js'
+import { bootstrap } from './bootstrap.js'
+import { describeConfig } from './describe.js'
+import { registerDescribeRoute, registerStatusRoute } from './route.js'
 
-/** Cordis plugin name used by loader diagnostics. */
+/** Loader 诊断里用的 Cordis 插件名。 */
 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(100).default(20).volatile().description('Default result cap; the hard cap is 100.'),
-  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(20000).default(8000).volatile().description('Default local_search_read window; the hard cap is 20,000 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.'),
-})
+/** profile 行 id，同时也是设置命名空间与卡片 id；三者必须一致。 */
+export const ENTRY_ID = 'fishdivinity-local-search'
 
-export { validateConfig }
+/**
+ * 「还在探测」对外最多声称多久。
+ *
+ * 注入回调只有在 settings 服务出现时才跑；部署里根本没有这个服务时它永远不来，`describe`
+ * 就会一直报 `autoconfig.pending`。10 秒足够覆盖正常的 loader 安顿 + 一次探测。
+ */
+const PENDING_GIVE_UP_MS = 10000
+
+export { Config, 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
+ * @param {object} config - schema 输出；volatile 字段是活引用
  */
 export async function apply(ctx, config) {
   validateConfig(config, MAX_TIMER_DELAY_MS)
 
+  // 首用配置的进展要能被 describe 读到，所以先建一个就地更新的状态对象，再由后台任务填。
+  const autoconfig = { pending: true, ran: false, failures: [] }
+  // 没有 settings 的部署里注入回调永远不会跑：给「还在探测」一个上限，免得 /describe 永远这么报。
+  const pendingDeadline = setTimeout(() => { autoconfig.pending = false }, PENDING_GIVE_UP_MS)
+  ctx.effect(() => () => { clearTimeout(pendingDeadline) })
+  ctx.inject(['settings'], (settingsCtx) => {
+    settingsCtx.effect(() => {
+      // 迁移旧键 → 按需探测 → 写回。
+      //
+      // 必须等 loader 把每一行都安顿好：settings.describe() 只列已经激活的行，而自己这行在
+      // apply 期间还没进入 active 状态，早跑一步就会「找不到可写的命名空间」并静默跳过。
+      // dsh-settings 迁移 settings.yaml 用的也是这个时机。
+      const loader = ctx.root?.loader
+      const settled = typeof loader?.await === 'function' ? loader.await() : Promise.resolve()
+      void settled
+        .then(() => bootstrap({ settings: settingsCtx.get('settings'), ns: ENTRY_ID, config, logger: ctx.logger }))
+        .then((state) => {
+          autoconfig.ran = state.ran
+          autoconfig.failures = state.failures
+          // 写回失败在页面上看不出来：把错误带进 describe，排查时不用猜。
+          autoconfig.error = state.error
+          if (state.written.length > 0) {
+            ctx.logger?.info?.('dsh-local-search: startup write: %s', state.written.join(', '))
+          }
+        })
+        .catch((error) => {
+          // 启动配置失败只降级：工具照旧读配置，只是旧键留在原地。
+          ctx.logger?.warn?.('dsh-local-search: first-run configuration failed', error)
+        })
+        .finally(() => {
+          autoconfig.pending = false
+        })
+    }, 'local-search: first-run configuration')
+  })
+
   ctx.effect(() => {
     const disposers = createTools(ctx, config).map((tool) => ctx.tools.register(tool))
     return () => {
@@ -48,26 +75,36 @@ export async function apply(ctx, config) {
     }
   })
 
+  // 这是路由提示，不是工具目录：每个工具的 description 已经说了自己是干什么的，这里只排选择
+  // 的顺序并点出回退方案。四句、约 250 字符——同样的决策，字数只有上一版的一半。
   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.',
+        '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.
+  // 配置页的两个只读接口：页面不能自己 POST 本机 Anytxt JSON-RPC，也无法知道装了哪些后端，
+  // 所以由 Host 代答。没有 web server 的部署就没有这两个接口，也没有页面。
   ctx.inject(['webServer'], (webCtx) => {
     const server = webCtx.get('webServer')
-    webCtx.effect(
-      () => registerStatusRoute(server, config),
-      'local-search: configuration page probe route',
-    )
+    const describe = () => describeConfig({
+      pending: autoconfig.pending,
+      ran: autoconfig.ran,
+      failures: autoconfig.failures,
+    })
+    webCtx.effect(() => {
+      const disposeStatus = registerStatusRoute(server, config)
+      const disposeDescribe = registerDescribeRoute(server, describe)
+      return () => {
+        disposeStatus()
+        disposeDescribe()
+      }
+    }, 'local-search: configuration page routes')
   })
 }

package/lib/limits.js

@@ -0,0 +1,13 @@
+/**
+ * 一次调用可以要到的硬上限。
+ *
+ * schema 卡的是保存下来的默认值，工具卡的是每次调用的参数，配置页镜像同一组数字，保存才不会
+ * 被拒。放在一处是为了只有一个值；页面没法 import 这个文件（普通脚本没有 ESM import），所以
+ * 它那份副本由一条测试比对。
+ */
+
+/** 结果条数的硬上限。 */
+export const MAX_LIMIT = 100
+
+/** 单次读取返回字符数的硬上限。 */
+export const MAX_READ = 20000

package/lib/probe.js

@@ -1,47 +1,60 @@
 /**
- * One probe of both local indexes, shared by the model-facing
- * `local_search_status` tool and the configuration page's Test control.
+ * 对两个本地索引各探测一次，供面向模型的 `local_search_status` 工具与配置页的测试按钮共用。
  *
- * 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`.
+ * 两边回答的是同一个问题——「这台机器现在能连上它的索引吗？」——所以不能漂成两份略有差异的
+ * 探测。探测走引擎注册表，新增后端仍然只是 `lib/engines.js` 里的一条。
  */
 
 import { readConfig } from './config.js'
 import { resolveContentEngine, resolveFilesEngine } from './engines.js'
+import { everythingInstalled } from './everything.js'
 
 /**
- * Probe the configured indexes once, never throwing.
- * @param {object} config - schema output, volatile references included
+ * Everything 这条链上缺的是哪一环。
+ *
+ * 这个细节是给读配置页的人看的，他能装或能启动点什么；模型只拿两个稳定 code。安装检查本身
+ * 就跑不起来时答案是 `unknown`，页面回落到它的通用提示，而不是让一个已经装了的人去安装。
+ * @param {string} code - 探测产生的错误码
+ * @returns {'not-installed'|'not-running'|'es-missing'|'unknown'} 能照着做的原因
+ */
+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'
+}
+
+/**
+ * 探测配置的索引一次，永不抛异常。
+ * @param {object} config - schema 输出，含 volatile 引用
  * @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 {AbortSignal} [options.signal] - caller cancellation
- * @returns {Promise<{everything: object, anytxt: object}>} both statuses
+ * @param {string} [options.only] - `auto` 两个都探；`anytxt` / `everything` 跳过另一个
+ * @param {string} [options.workspace] - 向 Anytxt 询问时用的根
+ * @param {string} [options.anytxtUrl] - 要探测的地址，而不是已保存的那个（页面的草稿）
+ * @param {boolean} [options.detail] - 给失败的引擎补上页面用的原因
+ * @param {AbortSignal} [options.signal] - 调用方的取消
+ * @returns {Promise<{everything: object, anytxt: object}>} 两个状态
  */
-export async function probeEngines(config, { only = 'auto', workspace, anytxtUrl, signal } = {}) {
+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.
+  // 探测是诊断而不是检索：除了上限还得有下限，否则一个很小的 timeoutMs 会把健康的引擎报成
+  // 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,
+        esPath: cfg.files.everything.esPath,
         timeoutMs: probeBudget,
         signal,
-        encoding: cfg.esEncoding,
+        encoding: cfg.files.everything.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'
@@ -51,8 +64,8 @@ export async function probeEngines(config, { only = 'auto', workspace, anytxtUrl
   if (only !== 'everything') {
     try {
       Object.assign(anytxt, await resolveContentEngine('anytxt').status({
-        url: anytxtUrl || cfg.anytxtUrl,
-        root: workspace || cfg.workspaceRoot || process.cwd(),
+        url: anytxtUrl || cfg.content.anytxt.url,
+        root: workspace || cfg.scopes.workspaceRoot || process.cwd(),
         timeoutMs: probeBudget,
         signal,
       }))

package/lib/ref.js

@@ -1,9 +1,9 @@
 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.
+ * ref 自带引擎名：`<engine>:<id>`。模型把过期的 ref 递回 local_search_read /
+ * local_search_fragments 时，Recoll 的 docid、Everything 的 fid 与将来的 Windows Search
+ * 条目才不会撞在一起。
  */
 export function formatRef(engine, id) {
   if (!engine || typeof engine !== 'string') {
@@ -15,7 +15,7 @@ export function formatRef(engine, id) {
   return `${engine}:${String(id)}`
 }
 
-/** Parse `<engine>:<id>`; reject bare ids with an actionable hint. */
+/** 解析 `<engine>:<id>`；裸 id 直接拒掉，并给一条能照着做的提示。 */
 export function parseRef(ref) {
   const text = String(ref ?? '')
   const separator = text.indexOf(':')
@@ -27,7 +27,7 @@ export function parseRef(ref) {
   return { engine: text.slice(0, separator), id: text.slice(separator + 1) }
 }
 
-/** Ensure a ref belongs to the resolved engine. */
+/** 确认 ref 属于已经解析出来的引擎。 */
 export function assertRefEngine(parsed, engineName) {
   if (parsed.engine !== engineName) {
     throw new EngineError(`ref belongs to ${parsed.engine}, not ${engineName}`, 'INVALID_REF', {

package/lib/roots.js

@@ -4,7 +4,7 @@ import { EngineError } from './errors.js'
 
 export const SCOPES = ['workspace', 'work', 'personal', 'all']
 
-/** Default `all` roots: the system drive plus D: when present. */
+/** `all` 的默认根：系统盘，加上存在时的 D:。 */
 export function defaultAllRoots() {
   const roots = []
   const systemDrive = process.env.SystemDrive || 'C:'
@@ -16,7 +16,7 @@ export function defaultAllRoots() {
   return roots
 }
 
-/** Parse the semicolon-separated `allRoots` config. */
+/** 解析分号分隔的 `allRoots` 配置。 */
 export function parseAllRoots(value) {
   return String(value || '')
     .split(';')
@@ -24,7 +24,7 @@ export function parseAllRoots(value) {
     .filter(Boolean)
 }
 
-/** Validate one existing absolute directory root. */
+/** 校验一个已存在的绝对目录根。 */
 export function validateRoot(root, label = 'root') {
   if (!root || typeof root !== 'string' || !isAbsolute(root)) {
     throw new EngineError(`${label} must be an absolute directory: ${root ?? '(empty)'}`, 'ROOT_NOT_ABSOLUTE', {
@@ -36,8 +36,8 @@ export function validateRoot(root, label = 'root') {
       hint: `Set ${label} to an existing directory.`,
     })
   }
-  // A file passes existsSync but makes es.exe -path and Anytxt filterDir return
-  // nothing, which reads as "no results" instead of a configuration mistake.
+  // 文件也能过 existsSync，但会让 es.exe -path 与 Anytxt 的 filterDir 返回空：读起来像
+  // 「没有结果」，而不是配置写错了。
   if (!statSync(root).isDirectory()) {
     throw new EngineError(`${label} is not a directory: ${root}`, 'ROOT_NOT_DIRECTORY', {
       hint: `Set ${label} to a directory, not a file.`,
@@ -47,11 +47,29 @@ export function validateRoot(root, label = 'root') {
 }
 
 /**
- * Resolve the directories a call should search.
+ * 丢掉嵌套在另一个根里的根。
  *
- * `workspace` falls back to the session's default directory; `work` and
- * `personal` require explicit config; `all` uses `allRoots` or the C:/D:
- * defaults.
+ * Anytxt 的检索是每个根问一次再把 count 相加，重叠的根会把同一个文件数两遍：「x of y」的
+ * 表头虚高，`truncated` 也提前翻真。每棵独立的树只查一次同样更省。
+ * @param {string[]} roots - 已校验的绝对目录
+ * @returns {string[]} 不在另一个根里的那些根
+ */
+export function dedupeRoots(roots) {
+  // Windows 两种分隔符都认，所以比较时统一成一种写法，返回时仍用调用方自己的写法。
+  const normalized = roots.map((root) => root.replace(/[\\/]+$/, '').replace(/\//g, '\\').toLowerCase())
+  return roots.filter((root, index) => !normalized.some((other, otherIndex) => {
+    if (otherIndex === index) return false
+    // 同一棵树被写了两遍时只留第一次出现的那个。
+    if (normalized[index] === other) return otherIndex < index
+    return normalized[index].startsWith(`${other}\\`)
+  }))
+}
+
+/**
+ * 解析一次调用该搜哪些目录。
+ *
+ * `workspace` 回落到会话的默认目录；`work` 与 `personal` 必须显式配置；`all` 用 `allRoots`
+ * 或 C:/D: 的默认值。
  */
 export function rootsFor(scope, explicitPath, config, defaultWorkspace) {
   const normalized = scope || 'workspace'
@@ -64,30 +82,30 @@ export function rootsFor(scope, explicitPath, config, defaultWorkspace) {
     return [validateRoot(explicitPath, 'path')]
   }
   if (normalized === 'workspace') {
-    return [validateRoot(config.workspaceRoot || defaultWorkspace || process.cwd(), 'workspaceRoot')]
+    return [validateRoot(config?.scopes?.workspaceRoot || defaultWorkspace || process.cwd(), 'workspaceRoot')]
   }
   if (normalized === 'work') {
-    if (!config.workRoot) {
+    if (!config?.scopes?.workRoot) {
       throw new EngineError('workRoot is not configured', 'SCOPE_NOT_CONFIGURED', {
         hint: 'Set workRoot in the plugin config, or pass an explicit path.',
       })
     }
-    return [validateRoot(config.workRoot, 'workRoot')]
+    return [validateRoot(config.scopes.workRoot, 'workRoot')]
   }
   if (normalized === 'personal') {
-    if (!config.personalRoot) {
+    if (!config?.scopes?.personalRoot) {
       throw new EngineError('personalRoot is not configured', 'SCOPE_NOT_CONFIGURED', {
         hint: 'Set personalRoot in the plugin config, or pass an explicit path.',
       })
     }
-    return [validateRoot(config.personalRoot, 'personalRoot')]
+    return [validateRoot(config.scopes.personalRoot, 'personalRoot')]
   }
-  const configured = parseAllRoots(config.allRoots)
+  const configured = parseAllRoots(config?.scopes?.allRoots)
   const roots = (configured.length > 0 ? configured : defaultAllRoots()).filter((root) => existsSync(root))
   if (roots.length === 0) {
     throw new EngineError('no allRoots are available', 'SCOPE_NOT_CONFIGURED', {
       hint: 'Set allRoots to existing directories, or pass an explicit path.',
     })
   }
-  return roots
+  return dedupeRoots(roots)
 }