@agentskit/doc-bridge 1.2.4 → 1.3.0

package/src/index-builder/plugins/nx.ts

@@ -0,0 +1,161 @@
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs'
+import { basename, dirname, isAbsolute, relative, resolve, sep } from 'node:path'
+
+import type { DocBridgeConfigV1 } from '../../config/schema.js'
+import { detectPackageManager } from '../../lib/package-manager.js'
+import { toPosix } from '../../lib/paths.js'
+import { walkFiles } from '../../lib/walk.js'
+import type { DiscoveredPackage } from './pnpm-monorepo.js'
+
+const NX_SCAN_SKIP = new Set([
+  'node_modules',
+  '.git',
+  '.nx',
+  'dist',
+  'coverage',
+  '.doc-bridge',
+])
+const NX_PROJECT_NAME = /^(?:@[A-Za-z0-9._-]+\/)?[A-Za-z0-9][A-Za-z0-9._-]*$/
+
+type JsonRecord = Record<string, unknown>
+
+const isRecord = (value: unknown): value is JsonRecord =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const readJsonRecord = (path: string): JsonRecord | undefined => {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))
+    return isRecord(parsed) ? parsed : undefined
+  } catch {
+    return undefined
+  }
+}
+
+const safeProjectPath = (
+  root: string,
+  manifestDir: string,
+  declaredRoot?: unknown,
+): string | undefined => {
+  const candidate = typeof declaredRoot === 'string' ? resolve(root, declaredRoot) : manifestDir
+  const rel = toPosix(relative(root, candidate)) || '.'
+  if (isAbsolute(rel) || rel === '..' || rel.startsWith('../')) return undefined
+  try {
+    if (!lstatSync(candidate).isDirectory()) return undefined
+    const canonicalRoot = realpathSync.native(root)
+    const canonicalCandidate = realpathSync.native(candidate)
+    const canonicalRel = relative(canonicalRoot, canonicalCandidate)
+    if (
+      isAbsolute(canonicalRel) ||
+      canonicalRel === '..' ||
+      canonicalRel.startsWith(`..${sep}`)
+    ) {
+      return undefined
+    }
+  } catch {
+    return undefined
+  }
+  return rel
+}
+
+const packageId = (name: string): string =>
+  name.startsWith('@') ? (name.split('/').at(-1) ?? name) : name
+
+const commandPrefix = (root: string): string => {
+  const manager = detectPackageManager(root)
+  if (manager === 'pnpm') return 'pnpm exec nx run'
+  if (manager === 'yarn') return 'yarn nx run'
+  if (manager === 'bun') return 'bunx nx run'
+  return 'npx nx run'
+}
+
+const inferredChecks = (
+  root: string,
+  config: DocBridgeConfigV1,
+  projectName: string,
+  targets: ReadonlySet<string>,
+): string[] | undefined => {
+  const prefix = commandPrefix(root)
+  const strict = (config.gates?.preset ?? 'minimal') !== 'minimal'
+  const checks = [
+    ...(targets.has('test') ? [`${prefix} ${projectName}:test`] : []),
+    ...(strict && targets.has('lint') ? [`${prefix} ${projectName}:lint`] : []),
+  ]
+  return checks.length ? checks : undefined
+}
+
+type RankedProject = DiscoveredPackage & {
+  readonly rank: number
+  readonly targets: readonly string[]
+}
+
+export const discoverNxProjects = (
+  root: string,
+  config: DocBridgeConfigV1,
+): DiscoveredPackage[] => {
+  if (!existsSync(resolve(root, 'nx.json'))) return []
+
+  const manifests = walkFiles(root, {
+    extensions: ['project.json', 'package.json'],
+    skipDirs: NX_SCAN_SKIP,
+    maxFiles: 10_000,
+  })
+  const projects = new Map<string, RankedProject>()
+
+  for (const manifest of manifests) {
+    const json = readJsonRecord(manifest)
+    if (!json) continue
+    const manifestDir = dirname(manifest)
+    const manifestName = basename(manifest)
+    const isProjectJson = manifestName === 'project.json'
+    if (!isProjectJson && manifestName !== 'package.json') continue
+    const nx = json.nx
+    if (!isProjectJson && !isRecord(nx)) continue
+
+    const path = safeProjectPath(root, manifestDir, isProjectJson ? json.root : undefined)
+    if (!path) continue
+    const projectPackage = isProjectJson
+      ? readJsonRecord(resolve(root, path, 'package.json'))
+      : undefined
+    const projectName =
+      typeof json.name === 'string'
+        ? json.name
+        : typeof projectPackage?.name === 'string'
+          ? projectPackage.name
+          : basename(path === '.' ? root : path)
+    if (!NX_PROJECT_NAME.test(projectName)) continue
+
+    const targets = new Set<string>()
+    const targetRecord = isProjectJson ? json.targets : isRecord(nx) ? nx.targets : undefined
+    if (isRecord(targetRecord)) {
+      for (const target of Object.keys(targetRecord)) targets.add(target)
+    }
+    if (!isProjectJson && isRecord(json.scripts)) {
+      for (const script of Object.keys(json.scripts)) targets.add(script)
+    }
+
+    const id = packageId(projectName)
+    const rank = isProjectJson ? 2 : 1
+    const existing = projects.get(id)
+    if (existing && existing.path !== path) {
+      throw new Error(
+        `Nx project identity collision for "${id}": "${existing.name ?? id}" at "${existing.path}" and "${projectName}" at "${path}". Use unique Nx project names.`,
+      )
+    }
+    const mergedTargets = [...new Set([...(existing?.targets ?? []), ...targets])]
+    const projectJsonWins = rank >= (existing?.rank ?? 0)
+    const resolvedName = projectJsonWins ? projectName : (existing?.name ?? projectName)
+    const checks = inferredChecks(root, config, resolvedName, new Set(mergedTargets))
+    projects.set(id, {
+      id,
+      path,
+      name: resolvedName,
+      ...(checks ? { checks } : {}),
+      rank: projectJsonWins ? rank : (existing?.rank ?? rank),
+      targets: mergedTargets,
+    })
+  }
+
+  return [...projects.values()]
+    .sort((a, b) => a.id.localeCompare(b.id))
+    .map(({ rank: _rank, targets: _targets, ...project }) => project)
+}

package/src/index-builder/plugins/pnpm-monorepo.ts

@@ -9,6 +9,7 @@ export type DiscoveredPackage = {
   readonly id: string
   readonly path: string
   readonly name?: string
+  readonly checks?: readonly string[]
 }
 
 const parsePnpmWorkspace = (yaml: string): string[] => {

package/src/index-builder/watch-index.ts

@@ -13,6 +13,7 @@ export type WatchIndexOptions = {
 }
 
 const WATCH_PATTERN = /\.(md|mdx|json|ya?ml|mdc)$/i
+const NX_MANIFEST_PATTERN = /(^|[/\\])(project|package)\.json$/i
 
 const collectWatchRoots = (root: string, config: DocBridgeConfigV1, configPath?: string): string[] => {
   const roots = new Set<string>()
@@ -24,7 +25,7 @@ const collectWatchRoots = (root: string, config: DocBridgeConfigV1, configPath?:
     : []
   for (const source of humanSources) {
     const humanOpts = source.options ?? {}
-    for (const key of ['contentDir', 'docsDir', 'root']) {
+    for (const key of ['contentDir', 'docsDir', 'root', 'srcDir']) {
       const value = humanOpts[key]
       if (typeof value === 'string' && value.length) roots.add(resolve(root, value))
     }
@@ -74,6 +75,14 @@ export const watchDocBridgeIndex = (opts: WatchIndexOptions): Promise<number> =>
     })
   }
 
+  const nxRoot = resolve(opts.root)
+  if (opts.config.routing?.plugin === 'nx' && existsSync(nxRoot)) {
+    watch(nxRoot, { recursive: true }, (_event, filename) => {
+      if (!filename || !NX_MANIFEST_PATTERN.test(filename)) return
+      rebuild()
+    })
+  }
+
   const configDir = resolve(opts.root)
   if (existsSync(configDir)) {
     watch(configDir, (_event, filename) => {
@@ -91,4 +100,4 @@ export const watchDocBridgeIndex = (opts: WatchIndexOptions): Promise<number> =>
     process.once('SIGINT', onSignal)
     process.once('SIGTERM', onSignal)
   })
-}
+}

package/src/index.ts

@@ -155,6 +155,7 @@ export {
 export { PACKAGE_VERSION } from './version.js'
 
 export { collectPackages, buildLookup } from './index-builder/build-handoffs.js'
+export { discoverNxProjects } from './index-builder/plugins/nx.js'
 export { projectRootFromConfigPath } from './config/load-config.js'
 export { createDocBridgeRag } from './intelligence/rag.js'
 export { runChatOnce, startInkChat } from './intelligence/chat.js'

package/src/mcp/server.ts

@@ -30,7 +30,9 @@ type McpContext = {
 export const MCP_TOOLS = [
   {
     name: 'handoff.resolve',
-    description: 'Resolve a package or ownership id to an AgentHandoff.',
+    title: 'Resolve repository handoff',
+    description: 'Resolve a package or ownership id to its deterministic AgentHandoff.',
+    annotations: { readOnlyHint: true },
     inputSchema: {
       type: 'object',
       properties: { id: { type: 'string' }, kind: { type: 'string', enum: ['package', 'ownership'] } },
@@ -39,7 +41,9 @@ export const MCP_TOOLS = [
   },
   {
     name: 'doc.search',
-    description: 'Search the deterministic doc-bridge index.',
+    title: 'Search repository documentation',
+    description: 'Search the deterministic Doc Bridge index for repository documentation.',
+    annotations: { readOnlyHint: true },
     inputSchema: {
       type: 'object',
       properties: { term: { type: 'string' }, limit: { type: 'number' } },
@@ -48,7 +52,9 @@ export const MCP_TOOLS = [
   },
   {
     name: 'doc.get',
-    description: 'Read an indexed agent documentation file by id or path.',
+    title: 'Read indexed documentation',
+    description: 'Read one indexed agent documentation file by id or indexed path.',
+    annotations: { readOnlyHint: true },
     inputSchema: {
       type: 'object',
       properties: { id: { type: 'string' }, path: { type: 'string' } },
@@ -56,12 +62,16 @@ export const MCP_TOOLS = [
   },
   {
     name: 'gate.status',
-    description: 'Run the index-freshness gate.',
+    title: 'Check documentation gates',
+    description: 'Evaluate documentation gates without writing files.',
+    annotations: { readOnlyHint: true },
     inputSchema: { type: 'object', properties: {} },
   },
   {
     name: 'retriever.query',
-    description: 'Return local doc-bridge retriever chunks for a query.',
+    title: 'Retrieve documentation context',
+    description: 'Return relevant local Doc Bridge index chunks for a query.',
+    annotations: { readOnlyHint: true },
     inputSchema: {
       type: 'object',
       properties: { query: { type: 'string' }, limit: { type: 'number' } },
@@ -70,17 +80,23 @@ export const MCP_TOOLS = [
   },
   {
     name: 'memory.classify',
-    description: 'Classify local memory candidates into agent/human/playbook/discard routes.',
+    title: 'Classify memory candidates',
+    description: 'Classify local memory candidates into agent, human, playbook, or discard routes.',
+    annotations: { readOnlyHint: true },
     inputSchema: { type: 'object', properties: {} },
   },
   {
     name: 'memory.promoteDraft',
-    description: 'Build a safe draft promotion body for local memory candidates.',
+    title: 'Draft memory promotion',
+    description: 'Build a reviewable draft promotion body from local memory candidates without publishing it.',
+    annotations: { readOnlyHint: true },
     inputSchema: { type: 'object', properties: {} },
   },
   {
     name: 'registry.topology',
-    description: 'Return the doc-curator registry topology.',
+    title: 'Inspect registry topology',
+    description: 'Return the static Doc Bridge curator and delegate topology.',
+    annotations: { readOnlyHint: true },
     inputSchema: { type: 'object', properties: {} },
   },
 ] as const
@@ -223,12 +239,14 @@ export const handleMcpRequest = (ctx: McpContext, request: JsonRpcRequest): unkn
   throw new Error(`Unsupported MCP method "${request.method ?? ''}"`)
 }
 
-const writeFrame = (payload: unknown): void => {
+type StdioFraming = 'content-length' | 'json-line'
+
+const writeFrame = (payload: unknown, framing: StdioFraming): void => {
   const body = JSON.stringify(payload)
-  process.stdout.write(`Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`)
+  process.stdout.write(framing === 'json-line' ? `${body}\n` : `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`)
 }
 
-const respond = (ctx: McpContext, request: JsonRpcRequest): void => {
+const respond = (ctx: McpContext, request: JsonRpcRequest, framing: StdioFraming): void => {
   if (request.id === undefined) {
     try {
       handleMcpRequest(ctx, request)
@@ -240,13 +258,13 @@ const respond = (ctx: McpContext, request: JsonRpcRequest): void => {
 
   try {
     const result = handleMcpRequest(ctx, request)
-    writeFrame({ jsonrpc: '2.0', id: request.id, result: result ?? {} })
+    writeFrame({ jsonrpc: '2.0', id: request.id, result: result ?? {} }, framing)
   } catch (error) {
     writeFrame({
       jsonrpc: '2.0',
       id: request.id,
       error: { code: -32000, message: error instanceof Error ? error.message : String(error) },
-    })
+    }, framing)
   }
 }
 
@@ -255,21 +273,35 @@ export const startMcpStdioServer = (ctx: McpContext): void => {
   process.stdin.on('data', (chunk: Buffer) => {
     buffer = Buffer.concat([buffer, chunk])
     while (true) {
-      const headerEnd = buffer.indexOf('\r\n\r\n')
-      if (headerEnd === -1) return
-      const header = buffer.subarray(0, headerEnd).toString('utf8')
-      const match = /content-length:\s*(\d+)/i.exec(header)
-      if (!match?.[1]) {
-        buffer = buffer.subarray(headerEnd + 4)
+      if (/^content-length:/i.test(buffer.subarray(0, Math.min(buffer.length, 32)).toString('utf8'))) {
+        const headerEnd = buffer.indexOf('\r\n\r\n')
+        if (headerEnd === -1) return
+        const header = buffer.subarray(0, headerEnd).toString('utf8')
+        const match = /content-length:\s*(\d+)/i.exec(header)
+        if (!match?.[1]) {
+          buffer = buffer.subarray(headerEnd + 4)
+          continue
+        }
+        const length = Number(match[1])
+        const bodyStart = headerEnd + 4
+        const bodyEnd = bodyStart + length
+        if (buffer.length < bodyEnd) return
+        const raw = buffer.subarray(bodyStart, bodyEnd).toString('utf8')
+        buffer = buffer.subarray(bodyEnd)
+        respond(ctx, JSON.parse(raw) as JsonRpcRequest, 'content-length')
         continue
       }
-      const length = Number(match[1])
-      const bodyStart = headerEnd + 4
-      const bodyEnd = bodyStart + length
-      if (buffer.length < bodyEnd) return
-      const raw = buffer.subarray(bodyStart, bodyEnd).toString('utf8')
-      buffer = buffer.subarray(bodyEnd)
-      respond(ctx, JSON.parse(raw) as JsonRpcRequest)
+
+      const lineEnd = buffer.indexOf('\n')
+      if (lineEnd === -1) return
+      const raw = buffer.subarray(0, lineEnd).toString('utf8').trim()
+      buffer = buffer.subarray(lineEnd + 1)
+      if (!raw) continue
+      try {
+        respond(ctx, JSON.parse(raw) as JsonRpcRequest, 'json-line')
+      } catch {
+        writeFrame({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }, 'json-line')
+      }
     }
   })
   process.stdin.resume()

package/src/version.ts

@@ -1 +1 @@
-export const PACKAGE_VERSION = '1.2.4'
+export const PACKAGE_VERSION = '1.3.0'