@agentskit/doc-bridge 0.1.0-alpha.1 → 0.1.0-alpha.3

package/src/lib/package-manager.ts

@@ -0,0 +1,104 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export type PackageManager = 'pnpm' | 'npm' | 'yarn' | 'bun'
+
+export const detectPackageManager = (root: string): PackageManager => {
+  if (existsSync(join(root, 'pnpm-lock.yaml')) || existsSync(join(root, 'pnpm-workspace.yaml'))) {
+    return 'pnpm'
+  }
+  if (existsSync(join(root, 'yarn.lock'))) return 'yarn'
+  if (existsSync(join(root, 'bun.lockb')) || existsSync(join(root, 'bun.lock'))) return 'bun'
+  if (existsSync(join(root, 'package-lock.json'))) return 'npm'
+
+  try {
+    const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as {
+      packageManager?: string
+    }
+    const pm = pkg.packageManager?.split('@')[0]
+    if (pm === 'pnpm' || pm === 'npm' || pm === 'yarn' || pm === 'bun') return pm
+  } catch {
+    // ignore
+  }
+
+  return 'npm'
+}
+
+export const defaultChecksForTarget = (
+  root: string,
+  opts: {
+    readonly packageId: string
+    readonly packagePath: string
+    readonly packageName?: string
+    readonly strict?: boolean
+  },
+): string[] => {
+  const pm = detectPackageManager(root)
+
+  // Pattern / markdown ownership targets (playbook, etc.) — project-level scripts
+  if (/\.mdx?$/.test(opts.packagePath) || opts.packagePath.includes('/pillars/')) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as {
+        scripts?: Record<string, string>
+      }
+      const scripts = pkg.scripts ?? {}
+      if (scripts['check:okf-type']) return ['pnpm run check:okf-type']
+      if (scripts['docs:bridge:gate']) return ['pnpm run docs:bridge:gate']
+      if (scripts.test) return [pm === 'pnpm' ? 'pnpm test' : 'npm test']
+    } catch {
+      // fall through
+    }
+  }
+
+  const isWorkspace =
+    existsSync(join(root, 'pnpm-workspace.yaml')) ||
+    existsSync(join(root, 'lerna.json')) ||
+    Boolean(
+      (() => {
+        try {
+          const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as {
+            workspaces?: unknown
+          }
+          return Boolean(pkg.workspaces)
+        } catch {
+          return false
+        }
+      })(),
+    )
+
+  const filter =
+    opts.packageName ??
+    (opts.packagePath.startsWith('packages/') || opts.packagePath.startsWith('apps/')
+      ? opts.packageId
+      : undefined)
+
+  if (pm === 'pnpm') {
+    if (isWorkspace && filter) {
+      const base = [`pnpm --filter ${filter} test`]
+      if (opts.strict) base.push(`pnpm --filter ${filter} lint`)
+      return base
+    }
+    return opts.strict ? ['pnpm test', 'pnpm run lint'] : ['pnpm test']
+  }
+
+  if (pm === 'yarn') {
+    if (isWorkspace && filter) {
+      return opts.strict
+        ? [`yarn workspace ${filter} test`, `yarn workspace ${filter} lint`]
+        : [`yarn workspace ${filter} test`]
+    }
+    return opts.strict ? ['yarn test', 'yarn lint'] : ['yarn test']
+  }
+
+  if (pm === 'bun') {
+    return opts.strict ? ['bun test', 'bun run lint'] : ['bun test']
+  }
+
+  // npm
+  if (isWorkspace && filter) {
+    return opts.strict
+      ? [`npm test -w ${filter}`, `npm run lint -w ${filter}`]
+      : [`npm test -w ${filter}`]
+  }
+  return opts.strict ? ['npm test', 'npm run lint'] : ['npm test']
+}

package/src/lib/paths.ts

@@ -0,0 +1,6 @@
+import { resolve } from 'node:path'
+
+export const toPosix = (value: string): string => value.split('\\').join('/')
+
+export const resolveFromRoot = (root: string, rel: string): string =>
+  resolve(root, rel)

package/src/lib/walk.ts

@@ -0,0 +1,45 @@
+import { readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { toPosix } from './paths.js'
+
+const DEFAULT_SKIP = new Set(['node_modules', '.git', 'dist', 'coverage', '.doc-bridge'])
+
+export const walkFiles = (
+  root: string,
+  opts?: { readonly extensions?: readonly string[]; readonly skipDirs?: ReadonlySet<string> },
+): string[] => {
+  const extensions = opts?.extensions ?? ['.md']
+  const skip = opts?.skipDirs ?? DEFAULT_SKIP
+  const out: string[] = []
+
+  const visit = (dir: string) => {
+    let entries: string[] = []
+    try {
+      entries = readdirSync(dir)
+    } catch {
+      return
+    }
+    for (const name of entries) {
+      const abs = join(dir, name)
+      let st
+      try {
+        st = statSync(abs)
+      } catch {
+        continue
+      }
+      if (st.isDirectory()) {
+        if (skip.has(name)) continue
+        visit(abs)
+        continue
+      }
+      if (!st.isFile()) continue
+      if (extensions.some((ext) => name.endsWith(ext))) {
+        out.push(toPosix(abs))
+      }
+    }
+  }
+
+  visit(root)
+  return out.sort()
+}

package/src/mcp/server.ts

@@ -0,0 +1,276 @@
+import { readFileSync, realpathSync } from 'node:fs'
+import { relative, resolve } from 'node:path'
+
+import { z, ZodError } from 'zod'
+
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import { retrieveDocBridgeChunks } from '../retriever/doc-bridge-retriever.js'
+import { runGates } from '../gates/run-gates.js'
+import { ingestMemoryCandidates } from '../memory/ingest.js'
+import { classifyMemoryCandidates, draftMemoryPromotion } from '../memory/pipeline.js'
+import { loadDocBridgeIndex } from '../query/load-index.js'
+import { runQuery } from '../query/query.js'
+import { searchIndex } from '../query/search.js'
+import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
+import { PACKAGE_VERSION } from '../version.js'
+
+type JsonRpcRequest = {
+  readonly jsonrpc?: '2.0'
+  readonly id?: string | number | null
+  readonly method?: string
+  readonly params?: unknown
+}
+
+type McpContext = {
+  readonly root: string
+  readonly config: DocBridgeConfigV1
+  readonly loadIndex?: () => DocBridgeIndexV1
+}
+
+export const MCP_TOOLS = [
+  {
+    name: 'handoff.resolve',
+    description: 'Resolve a package or ownership id to an AgentHandoff.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'string' }, kind: { type: 'string', enum: ['package', 'ownership'] } },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'doc.search',
+    description: 'Search the deterministic doc-bridge index.',
+    inputSchema: {
+      type: 'object',
+      properties: { term: { type: 'string' }, limit: { type: 'number' } },
+      required: ['term'],
+    },
+  },
+  {
+    name: 'doc.get',
+    description: 'Read an indexed agent documentation file by id or path.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'string' }, path: { type: 'string' } },
+    },
+  },
+  {
+    name: 'gate.status',
+    description: 'Run the index-freshness gate.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'retriever.query',
+    description: 'Return local doc-bridge retriever chunks for a query.',
+    inputSchema: {
+      type: 'object',
+      properties: { query: { type: 'string' }, limit: { type: 'number' } },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'memory.classify',
+    description: 'Classify local memory candidates into agent/human/playbook/discard routes.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'memory.promoteDraft',
+    description: 'Build a safe draft promotion body for local memory candidates.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'registry.topology',
+    description: 'Return the doc-curator registry topology.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+] as const
+
+const asRecord = (value: unknown): Record<string, unknown> =>
+  value && typeof value === 'object' ? (value as Record<string, unknown>) : {}
+
+const HandoffResolveArgsSchema = z.object({
+  id: z.string().min(1),
+  kind: z.enum(['package', 'ownership']).optional(),
+})
+
+const DocSearchArgsSchema = z.object({
+  term: z.string().min(1),
+  limit: z.number().int().positive().max(100).optional(),
+})
+
+const RetrieverQueryArgsSchema = z.object({
+  query: z.string().min(1),
+  limit: z.number().int().positive().max(100).optional(),
+})
+
+const DocGetArgsSchema = z
+  .object({
+    id: z.string().min(1).optional(),
+    path: z.string().min(1).optional(),
+  })
+  .refine((args) => args.id || args.path, 'doc.get requires id or path')
+
+const parseToolArgs = <T>(tool: string, schema: z.ZodType<T>, value: unknown): T => {
+  try {
+    return schema.parse(value)
+  } catch (error) {
+    if (error instanceof ZodError) {
+      throw new Error(`${tool} invalid arguments: ${error.issues.map((issue) => issue.message).join(', ')}`)
+    }
+    throw error
+  }
+}
+
+const textResult = (value: unknown) => ({
+  content: [
+    {
+      type: 'text',
+      text: typeof value === 'string' ? value : JSON.stringify(value, null, 2),
+    },
+  ],
+})
+
+const findDocPath = (index: DocBridgeIndexV1, args: z.infer<typeof DocGetArgsSchema>): string => {
+  if (args.path) {
+    const doc = index.knowledge.find((entry) => entry.path === args.path)
+    if (!doc) throw new Error(`Unknown indexed doc path "${args.path}"`)
+    return doc.path
+  }
+  const id = args.id ?? ''
+  const doc = index.knowledge.find((entry) => entry.id === args.id)
+  if (!doc) throw new Error(`Unknown doc id "${id}"`)
+  return doc.path
+}
+
+const resolveDocPath = (root: string, relPath: string): string => {
+  const rootAbs = realpathSync.native(root)
+  const unresolved = resolve(rootAbs, relPath)
+  const unresolvedRel = relative(rootAbs, unresolved)
+  if (unresolvedRel.startsWith('..')) throw new Error('doc.get path escapes project root')
+  const abs = realpathSync.native(unresolved)
+  const rel = relative(rootAbs, abs)
+  if (rel.startsWith('..')) throw new Error('doc.get path escapes project root')
+  return abs
+}
+
+export const handleMcpRequest = (ctx: McpContext, request: JsonRpcRequest): unknown => {
+  if (request.method === 'initialize') {
+    return {
+      protocolVersion: '2024-11-05',
+      capabilities: { tools: {} },
+      serverInfo: { name: 'ak-docs', version: PACKAGE_VERSION },
+    }
+  }
+
+  if (request.method === 'tools/list') return { tools: MCP_TOOLS }
+
+  if (request.method === 'tools/call') {
+    const params = asRecord(request.params)
+    const name = params.name
+    const args = asRecord(params.arguments)
+    const index = () => ctx.loadIndex?.() ?? loadDocBridgeIndex(ctx.root, ctx.config)
+
+    if (name === 'handoff.resolve') {
+      const parsed = parseToolArgs('handoff.resolve', HandoffResolveArgsSchema, args)
+      return textResult(
+        runQuery(index(), ctx.config, {
+          kind: parsed.kind === 'package' ? 'package' : 'ownership',
+          id: parsed.id,
+          agent: true,
+        }),
+      )
+    }
+
+    if (name === 'doc.search') {
+      const parsed = parseToolArgs('doc.search', DocSearchArgsSchema, args)
+      return textResult(searchIndex(index(), parsed.term, parsed.limit ?? 20))
+    }
+
+    if (name === 'doc.get') {
+      const relPath = findDocPath(index(), parseToolArgs('doc.get', DocGetArgsSchema, args))
+      return textResult(readFileSync(resolveDocPath(ctx.root, relPath), 'utf8'))
+    }
+
+    if (name === 'gate.status') return textResult(runGates(ctx.root, ctx.config))
+
+    if (name === 'retriever.query') {
+      const parsed = parseToolArgs('retriever.query', RetrieverQueryArgsSchema, args)
+      return textResult(retrieveDocBridgeChunks(index(), parsed.query, parsed.limit ? { limit: parsed.limit } : {}))
+    }
+
+    if (name === 'memory.classify') {
+      return textResult(classifyMemoryCandidates(ingestMemoryCandidates(ctx.root), index()))
+    }
+
+    if (name === 'memory.promoteDraft') {
+      return textResult(draftMemoryPromotion(classifyMemoryCandidates(ingestMemoryCandidates(ctx.root), index())))
+    }
+
+    if (name === 'registry.topology') {
+      return textResult({
+        id: 'doc-curator',
+        delegates: ['docs-chat', 'knowledge-promoter', 'code-review'],
+        tools: ['handoff.resolve', 'doc.search', 'doc.get', 'gate.status', 'retriever.query'],
+        steps: ['classify', 'draft', 'verify', 'review'],
+        mergePolicy: { autoMerge: false, requiresHuman: true },
+      })
+    }
+
+    throw new Error(`Unknown tool "${String(name)}"`)
+  }
+
+  if (request.method?.startsWith('notifications/')) return undefined
+  throw new Error(`Unsupported MCP method "${request.method ?? ''}"`)
+}
+
+const writeFrame = (payload: unknown): void => {
+  const body = JSON.stringify(payload)
+  process.stdout.write(`Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`)
+}
+
+const respond = (ctx: McpContext, request: JsonRpcRequest): void => {
+  if (request.id === undefined) {
+    try {
+      handleMcpRequest(ctx, request)
+    } catch {
+      // Notifications do not get responses.
+    }
+    return
+  }
+
+  try {
+    const result = handleMcpRequest(ctx, request)
+    writeFrame({ jsonrpc: '2.0', id: request.id, result: result ?? {} })
+  } catch (error) {
+    writeFrame({
+      jsonrpc: '2.0',
+      id: request.id,
+      error: { code: -32000, message: error instanceof Error ? error.message : String(error) },
+    })
+  }
+}
+
+export const startMcpStdioServer = (ctx: McpContext): void => {
+  let buffer = Buffer.alloc(0)
+  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)
+        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)
+    }
+  })
+  process.stdin.resume()
+}

package/src/memory/ingest.ts

@@ -0,0 +1,51 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { firstHeading, firstParagraph, slugFromPath } from '../lib/markdown.js'
+import { toPosix } from '../lib/paths.js'
+import { walkFiles } from '../lib/walk.js'
+import type { MemoryCandidateV1 } from '../schemas/memory-candidate.js'
+
+const memoryFact = (raw: string, id: string): string =>
+  firstParagraph(raw) ?? firstHeading(raw) ?? id
+
+const relativePath = (root: string, abs: string): string =>
+  toPosix(abs).replace(`${toPosix(root)}/`, '')
+
+const ingestMarkdownDir = (
+  root: string,
+  dir: string,
+  source: MemoryCandidateV1['source'],
+  confidence: number,
+): MemoryCandidateV1[] => {
+  if (!existsSync(dir)) return []
+
+  return walkFiles(dir, { extensions: ['.md', '.mdc'] }).map((abs) => {
+    const rel = relativePath(root, abs)
+    const raw = readFileSync(abs, 'utf8')
+    const id = slugFromPath(rel)
+    return {
+      schemaVersion: 1,
+      id,
+      source,
+      rawPath: rel,
+      fact: memoryFact(raw, id),
+      suggestedType: 'project',
+      confidence,
+      references: [],
+    }
+  })
+}
+
+export const ingestCursorRules = (root: string): MemoryCandidateV1[] => {
+  const dir = join(root, '.cursor', 'rules')
+  return ingestMarkdownDir(root, dir, 'cursor', 0.6)
+}
+
+export const ingestAgentMemory = (root: string): MemoryCandidateV1[] =>
+  ingestMarkdownDir(root, join(root, '.agent-memory'), 'agent-memory', 0.7)
+
+export const ingestMemoryCandidates = (root: string): MemoryCandidateV1[] => [
+  ...ingestAgentMemory(root),
+  ...ingestCursorRules(root),
+]

package/src/memory/pipeline.ts

@@ -0,0 +1,119 @@
+import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
+import type { MemoryCandidateV1 } from '../schemas/memory-candidate.js'
+import { searchIndex } from '../query/search.js'
+
+export type MemoryRoute = 'agent' | 'human' | 'playbook' | 'discard'
+
+export type MemoryClassification = {
+  readonly candidate: MemoryCandidateV1
+  readonly route: MemoryRoute
+  readonly reason: string
+  readonly target?: string
+  readonly duplicateOf?: string
+}
+
+export type SafetyFinding = {
+  readonly candidateId: string
+  readonly kind: 'secret' | 'private-email'
+  readonly message: string
+}
+
+export type MemoryPromotionDraft = {
+  readonly ok: boolean
+  readonly title: string
+  readonly body: string
+  readonly findings: SafetyFinding[]
+  readonly classifications: MemoryClassification[]
+}
+
+const packageOwnership = /\b(?:package|module)\s+([a-z0-9._/-]+)\s+(?:owns|owner|responsible|routes?)\b/i
+const secretPattern = /\b(?:api[_-]?key|token|secret|password)\s*[:=]\s*\S+/i
+const privateEmailPattern = /\b[A-Z0-9._%+-]+@(?!example\.com\b)[A-Z0-9.-]+\.[A-Z]{2,}\b/i
+
+const classifyRoute = (fact: string): Pick<MemoryClassification, 'route' | 'reason'> => {
+  if (/\b(noise|scratch|ignore|discard)\b/i.test(fact)) {
+    return { route: 'discard', reason: 'marked as noise' }
+  }
+  if (/\b(playbook|pattern|principle|best practice)\b/i.test(fact)) {
+    return { route: 'playbook', reason: 'generalizable pattern' }
+  }
+  if (/\b(user-facing|human guide|docs site|tutorial|guide)\b/i.test(fact)) {
+    return { route: 'human', reason: 'user-facing documentation' }
+  }
+  return { route: 'agent', reason: 'project convention or ownership note' }
+}
+
+export const classifyMemoryCandidates = (
+  candidates: readonly MemoryCandidateV1[],
+  index: DocBridgeIndexV1,
+): MemoryClassification[] =>
+  candidates.map((candidate) => {
+    const duplicate = searchIndex(index, candidate.fact, 1)[0]
+    const targetMatch = packageOwnership.exec(candidate.fact)
+    const route = classifyRoute(candidate.fact)
+    return {
+      candidate,
+      ...route,
+      ...(targetMatch?.[1] ? { target: targetMatch[1] } : {}),
+      ...(duplicate && duplicate.score >= 16 ? { duplicateOf: duplicate.path } : {}),
+    }
+  })
+
+export const scanMemorySafety = (
+  classifications: readonly MemoryClassification[],
+): SafetyFinding[] =>
+  classifications.flatMap(({ candidate }) => {
+    const findings: SafetyFinding[] = []
+    if (secretPattern.test(candidate.fact)) {
+      findings.push({
+        candidateId: candidate.id,
+        kind: 'secret',
+        message: 'Potential secret-like value in memory fact',
+      })
+    }
+    if (privateEmailPattern.test(candidate.fact)) {
+      findings.push({
+        candidateId: candidate.id,
+        kind: 'private-email',
+        message: 'Potential private email in memory fact',
+      })
+    }
+    return findings
+  })
+
+export const draftMemoryPromotion = (
+  classifications: readonly MemoryClassification[],
+): MemoryPromotionDraft => {
+  const findings = scanMemorySafety(classifications)
+  const safe = findings.length === 0
+  const lines = classifications.map(({ candidate, route, reason, target, duplicateOf }) =>
+    [
+      `- ${candidate.id}: ${route}`,
+      `reason=${reason}`,
+      target ? `target=${target}` : undefined,
+      duplicateOf ? `duplicateOf=${duplicateOf}` : undefined,
+      `fact=${candidate.fact}`,
+    ].filter(Boolean).join(' | '),
+  )
+
+  return {
+    ok: safe,
+    title: 'Draft doc-bridge memory promotion',
+    body: [
+      '# Draft doc-bridge memory promotion',
+      '',
+      safe ? 'Safety scan: pass.' : 'Safety scan: blocked. Redact findings before PR.',
+      '',
+      '## Candidates',
+      '',
+      ...lines,
+      '',
+      '## Policy',
+      '',
+      '- Draft only; never auto-merge.',
+      '- Run doc-bridge gates before opening a PR.',
+    ].join('\n'),
+    findings,
+    classifications: [...classifications],
+  }
+}

package/src/query/load-index.ts

@@ -0,0 +1,25 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
+import { parseDocBridgeIndex } from '../validate.js'
+
+export class IndexNotFoundError extends Error {
+  constructor(readonly path: string) {
+    super(`Missing index at ${path}. Run: ak-docs index`)
+    this.name = 'IndexNotFoundError'
+  }
+}
+
+export const indexFilePath = (root: string, config: DocBridgeConfigV1): string =>
+  join(root, config.index?.outFile ?? '.doc-bridge/index.json')
+
+export const loadDocBridgeIndex = (root: string, config: DocBridgeConfigV1): DocBridgeIndexV1 => {
+  const path = indexFilePath(root, config)
+  if (!existsSync(path)) throw new IndexNotFoundError(path)
+  const raw = JSON.parse(readFileSync(path, 'utf8')) as unknown
+  return parseDocBridgeIndex(raw)
+}
+
+export const resolveRoot = (cwd?: string): string => resolve(cwd ?? process.cwd())