@lvy-jsd/dsh-tool-manager 0.2.0 → 0.4.0

package/src/manifest.ts

@@ -0,0 +1,116 @@
+// A tool manifest on disk, so a client that cannot lazy-load can still find tools.
+//
+// Claude Code (driven by dsh-oh-my-claude) receives dsh tools once per session
+// over an MCP bridge, built from what the session's agent can see at that
+// moment. The directory keeps ~240 tools out of every request, so what that
+// bridge lists is the always-on set plus `tools_ls`/`tools_load` — and nothing
+// tells Claude the directory exists, so it never asks.
+//
+// This file answers "what is there" without a call: the catalog as text, plus
+// the two tool names that load the rest. It is written next to Claude Code's
+// own instructions and pulled in with an `@` line, so every Claude session reads
+// it the same way it reads CLAUDE.md.
+//
+// Written after every catalog rebuild, and only when the text changed: the file
+// is part of a prompt, so a rewrite that changes nothing still costs a re-read
+// and a cache miss.
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import type { Catalog, Logger } from './types.js'
+
+/** Where the manifest goes unless a deployment points elsewhere. */
+export function defaultManifestFile(): string {
+  return join(homedir(), '.claude', 'dsh-tool-catalog.md')
+}
+
+/** One line describing what to do with this file, so a model reads it as instructions. */
+const HEADER = [
+  '# dsh tool catalog',
+  '',
+  'dsh keeps most of its tools out of every request and hands them out on demand.',
+  'The tools listed below are NOT callable yet — this file is the index, not the tools.',
+  '',
+  'To use one:',
+  '',
+  '- `tools_ls` browses the same tree as text: no argument lists categories, a',
+  '  category name lists its groups, a group lists its tools. `tools_ls({ query })`',
+  '  searches every name and description at once.',
+  '- `tools_load` makes tools callable for the rest of the session. Pass group',
+  '  paths (`/code/github`), a category (`/maps`), or exact tool names.',
+  '- Load the smallest thing that covers the task. A whole category costs more',
+  '  context than the one group you need.',
+  '- High-risk tools (marked `!`) need a risk gate to confirm them; with none',
+  '  installed, loading them is refused.',
+  '',
+  'This file is regenerated whenever the catalog changes; do not edit it.',
+  '',
+].join('\n')
+
+/**
+ * The catalog as markdown: category, then group, then tool names with their
+ * summaries. Summaries are cut to one line so a group of 30 tools stays
+ * scannable, and the counts let a reader judge a load before making it.
+ */
+export function renderManifest(catalog: Catalog): string {
+  const out: string[] = [HEADER]
+  const categories = [...catalog.categories.values()].sort((a, b) => a.name.localeCompare(b.name))
+  for (const category of categories) {
+    const tools = category.groups.flatMap((group) => group.tools)
+    if (tools.length === 0) continue
+    out.push(`## ${category.name} (${tools.length} tools, ${category.description || 'no description'})`, '')
+    for (const group of [...category.groups].sort((a, b) => a.name.localeCompare(b.name))) {
+      out.push(`### ${group.name} — load with \`tools_load({ targets: ["/${category.name}/${group.name}"] })\``)
+      for (const tool of group.tools) {
+        const risk = tool.highRisk ? ' !' : ''
+        const summary = tool.summary ? ` — ${tool.summary}` : ''
+        out.push(`- ${tool.name}${risk}${summary}`)
+      }
+      out.push('')
+    }
+  }
+  out.push('## Also always available', '')
+  out.push('- `tools_ls`, `tools_load`, `tools_unload` — the directory itself.', '')
+  return out.join('\n')
+}
+
+/** The smallest change worth a rewrite: identical text means no write at all. */
+function sameFile(file: string, text: string): boolean {
+  try {
+    return readFileSync(file, 'utf8') === text
+  } catch {
+    return false
+  }
+}
+
+/** Write atomically; a crash cannot leave a half-written prompt. */
+export function writeManifest(file: string, text: string, logger?: Logger): boolean {
+  if (sameFile(file, text)) return false
+  try {
+    mkdirSync(dirname(file), { recursive: true })
+    const temporary = `${file}.tmp`
+    writeFileSync(temporary, text, 'utf8')
+    renameSync(temporary, file)
+    return true
+  } catch (caught) {
+    // A read-only home is not a reason to break the catalog; the panel still works.
+    logger?.warn?.(`tool-manager: writing the tool manifest ${file} failed: ${(caught as Error).message}`)
+    return false
+  }
+}
+
+/** Write the manifest for this catalog, if it changed. */
+export function syncManifest(catalog: Catalog, file: string, logger?: Logger): boolean {
+  return writeManifest(file, renderManifest(catalog), logger)
+}
+
+/**
+ * The `@` line a CLAUDE.md needs to pull the manifest in.
+ *
+ * `@` has to open the line or follow whitespace, and a path with spaces is
+ * escaped — the same rules Claude Code applies to its own imports.
+ */
+export function manifestImport(file: string): string {
+  return `@${file.replace(/ /g, '\\ ')}`
+}

package/src/metadata.ts

@@ -0,0 +1,123 @@
+// Persisted tool metadata for dsh-tool-manager.
+//
+// A package declares its tools in package.json (`dsh.toolCatalog`), which a user
+// cannot edit from the browser. This file holds the same kind of metadata keyed
+// by tool name, written by the panel, and is applied after every other
+// annotation so an edit always wins over the declaration it corrects.
+//
+// Only metadata is stored here. A tool's parameters and description belong to
+// the host and its plugins; rewriting them for the model is not something a
+// directory plugin can do, and pretending otherwise would drift from what the
+// model actually receives.
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import type { Annotation, Logger, ToolMeta } from './types.js'
+
+const META_KEYS = ['group', 'category', 'risk', 'summary'] as const
+
+/** Where edited metadata is stored unless a deployment points elsewhere. */
+export function defaultMetadataFile(): string {
+  const dshHome = process.env.DSH_HOME || join(homedir(), '.config', 'deepseek-harness')
+  return join(dshHome, 'tool-manager', 'metadata.json')
+}
+
+/** Keep only known string fields; a blank value means "no override here". */
+export function pickMeta(raw: unknown): ToolMeta {
+  const out: ToolMeta = {}
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return out
+  for (const key of META_KEYS) {
+    const value = (raw as Record<string, unknown>)[key]
+    if (typeof value === 'string' && value.trim()) out[key] = value.trim()
+  }
+  return out
+}
+
+/** The whole file: tool name -> metadata. Unknown shapes are dropped. */
+export function pickMetadata(raw: unknown): Record<string, ToolMeta> {
+  const out: Record<string, ToolMeta> = {}
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return out
+  for (const [name, meta] of Object.entries(raw as Record<string, unknown>)) {
+    const picked = pickMeta(meta)
+    if (name && Object.keys(picked).length) out[name] = picked
+  }
+  return out
+}
+
+/** Read the metadata file; missing or corrupt is "no overrides", never a crash. */
+export function readMetadataFile(file: string, logger?: Logger): Record<string, ToolMeta> {
+  try {
+    return pickMetadata(JSON.parse(readFileSync(file, 'utf8')))
+  } catch (caught) {
+    const error = caught as NodeJS.ErrnoException
+    // ENOENT is the normal first run: no file means nothing has been edited.
+    if (error.code !== 'ENOENT') logger?.warn?.(`tool-manager: ignoring unreadable metadata ${file}: ${error.message}`)
+    return {}
+  }
+}
+
+/** Write the file atomically, so a crash cannot leave a half-written override. */
+export function writeMetadataFile(file: string, entries: Record<string, ToolMeta>, logger?: Logger): void {
+  mkdirSync(dirname(file), { recursive: true })
+  const tmp = `${file}.tmp`
+  try {
+    writeFileSync(tmp, `${JSON.stringify(entries, null, 2)}\n`)
+    renameSync(tmp, file)
+  } catch (caught) {
+    logger?.warn?.(`tool-manager: writing metadata ${file} failed: ${(caught as Error).message}`)
+    throw caught
+  }
+}
+
+export interface MetadataStore {
+  /** File the store reads and writes. */
+  file: string
+  /** Every override, keyed by tool name. */
+  all(): Record<string, ToolMeta>
+  /** The override for one tool, or undefined. */
+  get(name: string): ToolMeta | undefined
+  /**
+   * Replace the override for one tool. Fields left out are dropped rather than
+   * kept, because the panel editor submits the whole form: an emptied field
+   * must fall back to the package declaration, not silently keep its old value.
+   * An empty result removes the override.
+   */
+  set(name: string, meta: ToolMeta): ToolMeta | undefined
+  /** Drop the override for one tool. */
+  clear(name: string): void
+  /** Re-read the file, for after an external edit. */
+  reload(): Record<string, ToolMeta>
+  /** The overrides as annotations, for buildCatalog(). */
+  annotations(): Annotation[]
+}
+
+/** Metadata store over one file. */
+export function createMetadataStore({ file, logger }: { file: string, logger?: Logger }): MetadataStore {
+  let entries = readMetadataFile(file, logger)
+  return {
+    file,
+    all: () => ({ ...entries }),
+    get: (name) => entries[name],
+    set(name, meta) {
+      const picked = pickMeta(meta)
+      // A blank form is how the UI removes an override: leaving an empty object
+      // behind would shadow nothing while still showing up as "edited".
+      if (Object.keys(picked).length) entries[name] = picked
+      else delete entries[name]
+      writeMetadataFile(file, entries, logger)
+      return entries[name]
+    },
+    clear(name) {
+      delete entries[name]
+      writeMetadataFile(file, entries, logger)
+    },
+    reload() {
+      entries = readMetadataFile(file, logger)
+      return { ...entries }
+    },
+    annotations() {
+      return Object.entries(entries).map(([name, meta]) => ({ source: 'tool-manager:metadata', match: name, meta }))
+    },
+  }
+}

package/src/router/bm25.ts

@@ -0,0 +1,68 @@
+// A small, dependency-free BM25 index. It is the always-available baseline:
+// ranked retrieval that needs no model, no network, and no sidecar process.
+
+import type { Hit } from './types.js'
+
+export function tokenize(text: string): string[] {
+  const out: string[] = []
+  const flat = String(text ?? '').toLowerCase()
+  for (const m of flat.matchAll(/[a-z0-9_]+/g)) out.push(m[0])
+  for (const ch of flat) if ((ch.codePointAt(0) ?? 0) > 0x2e7f) out.push(ch)
+  return out
+}
+
+interface Doc {
+  id: number
+  ref: unknown
+  tf: Map<string, number>
+  len: number
+}
+
+export class Bm25<T> {
+  private k1: number
+  private b: number
+  private docs: Doc[] = []
+  private df = new Map<string, number>()
+  private avgLen = 0
+  private n = 0
+
+  constructor({ k1 = 1.5, b = 0.75 }: { k1?: number; b?: number } = {}) {
+    this.k1 = k1
+    this.b = b
+  }
+
+  build(docs: { ref: T; text: string }[]): void {
+    this.docs = docs.map((d, i) => {
+      const tokens = tokenize(d.text)
+      const tf = new Map<string, number>()
+      for (const t of tokens) tf.set(t, (tf.get(t) ?? 0) + 1)
+      return { id: i, ref: d.ref, tf, len: tokens.length }
+    })
+    this.df = new Map()
+    for (const doc of this.docs) for (const term of doc.tf.keys()) this.df.set(term, (this.df.get(term) ?? 0) + 1)
+    this.n = this.docs.length
+    this.avgLen = this.n ? this.docs.reduce((s, d) => s + d.len, 0) / this.n : 0
+  }
+
+  private idf(term: string): number {
+    const df = this.df.get(term) ?? 0
+    return Math.log((this.n - df + 0.5) / (df + 0.5) + 1)
+  }
+
+  search(query: string, limit = 8): Hit<T>[] {
+    const terms = [...new Set(tokenize(query))]
+    if (!terms.length || !this.n) return []
+    const scored: Hit<T>[] = []
+    for (const doc of this.docs) {
+      let score = 0
+      for (const term of terms) {
+        const tf = doc.tf.get(term) ?? 0
+        if (!tf) continue
+        score += this.idf(term) * (tf * (this.k1 + 1)) / (tf + this.k1 * (1 - this.b + this.b * (doc.len / (this.avgLen || 1))))
+      }
+      if (score > 0) scored.push({ ref: doc.ref as T, score })
+    }
+    scored.sort((a, b) => b.score - a.score)
+    return scored.slice(0, limit)
+  }
+}