@agentskit/doc-bridge 0.1.0-alpha.2 → 1.0.0

package/src/mcp/install.ts

@@ -0,0 +1,84 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+
+export type McpInstallTarget = 'cursor' | 'claude'
+
+export type McpInstallResult = {
+  readonly ok: boolean
+  readonly target: McpInstallTarget
+  readonly configPath: string
+  readonly created: boolean
+  readonly serverName: string
+  readonly nextSteps: readonly string[]
+}
+
+const SERVER_NAME = 'ak-docs'
+
+const mcpServerEntry = (root: string) => ({
+  command: 'npx',
+  args: ['ak-docs', 'mcp'],
+  cwd: root,
+})
+
+const readJson = (path: string): Record<string, unknown> => {
+  if (!existsSync(path)) return {}
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as unknown
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : {}
+  } catch {
+    return {}
+  }
+}
+
+const writeJson = (path: string, value: Record<string, unknown>): void => {
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, 'utf8')
+}
+
+const resolveTargetPath = (target: McpInstallTarget, root: string): string => {
+  if (target === 'cursor') return resolve(root, '.cursor', 'mcp.json')
+  return join(homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json')
+}
+
+export const installMcpConfig = (
+  root: string,
+  target: McpInstallTarget,
+): McpInstallResult => {
+  const configPath = resolveTargetPath(target, root)
+  const created = !existsSync(configPath)
+  const existing = readJson(configPath)
+  const servers =
+    existing.mcpServers && typeof existing.mcpServers === 'object' && !Array.isArray(existing.mcpServers)
+      ? { ...(existing.mcpServers as Record<string, unknown>) }
+      : {}
+
+  servers[SERVER_NAME] = mcpServerEntry(root)
+  writeJson(configPath, { ...existing, mcpServers: servers })
+
+  const nextSteps =
+    target === 'cursor'
+      ? [
+          'Restart Cursor or reload MCP servers',
+          'Paste the doc-bridge skill into Cursor rules (see docs/skills/doc-bridge.md)',
+          'Before editing packages/* call handoff.resolve',
+        ]
+      : [
+          'Restart Claude Desktop',
+          'Run ak-docs index after doc changes',
+        ]
+
+  return {
+    ok: true,
+    target,
+    configPath,
+    created,
+    serverName: SERVER_NAME,
+    nextSteps,
+  }
+}
+
+export const mcpSnippet = (root: string): string =>
+  JSON.stringify({ mcpServers: { [SERVER_NAME]: mcpServerEntry(root) } }, null, 2)

package/src/memory/github-pr.ts

@@ -0,0 +1,190 @@
+import { execFileSync, spawnSync } from 'node:child_process'
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { MemoryPromotionDraft } from './pipeline.js'
+
+export type GithubPrOptions = {
+  readonly dryRun?: boolean
+  readonly force?: boolean
+  readonly branch?: string
+  readonly base?: string
+}
+
+export type GithubPrResult = {
+  readonly ok: boolean
+  readonly dryRun: boolean
+  readonly draftPath: string
+  readonly branch: string
+  readonly prUrl?: string
+  readonly previewUrl?: string
+  readonly commands: readonly string[]
+  readonly message: string
+}
+
+const run = (cmd: string, args: readonly string[], cwd: string): { ok: boolean; out: string } => {
+  const result = spawnSync(cmd, [...args], { cwd, encoding: 'utf8' })
+  const out = `${result.stdout ?? ''}${result.stderr ?? ''}`.trim()
+  return { ok: result.status === 0, out }
+}
+
+const hasGh = (): boolean => run('gh', ['--version'], process.cwd()).ok
+
+const slug = (): string => new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)
+
+export const defaultPromotionDraftPath = (root: string): string =>
+  join(root, '.doc-bridge', 'drafts', `memory-promotion-${slug()}.md`)
+
+export const writePromotionDraft = (root: string, draft: MemoryPromotionDraft, path?: string): string => {
+  const draftPath = path ?? defaultPromotionDraftPath(root)
+  mkdirSync(join(root, '.doc-bridge', 'drafts'), { recursive: true })
+  writeFileSync(draftPath, `${draft.body}\n`, 'utf8')
+  return draftPath
+}
+
+export const promoteMemoryToGithubPr = (
+  root: string,
+  draft: MemoryPromotionDraft,
+  options: GithubPrOptions = {},
+): GithubPrResult => {
+  if (!draft.ok && !options.force) {
+    return {
+      ok: false,
+      dryRun: Boolean(options.dryRun),
+      draftPath: '',
+      branch: '',
+      commands: [],
+      message: 'Safety scan blocked promotion. Fix findings or pass --force to draft anyway.',
+    }
+  }
+
+  const branch = options.branch ?? `doc-bridge/memory-promotion-${slug()}`
+  const draftPath = writePromotionDraft(root, draft)
+  const relDraft = draftPath.startsWith(`${root}/`) ? draftPath.slice(root.length + 1) : draftPath
+
+  const commands = [
+    `git checkout -b ${branch}`,
+    `git add ${relDraft}`,
+    `git commit -m "draft: doc-bridge memory promotion"`,
+    `git push -u origin ${branch}`,
+    `gh pr create --draft --title "${draft.title}" --body-file ${relDraft}${options.base ? ` --base ${options.base}` : ''}`,
+  ]
+
+  if (options.dryRun) {
+    return {
+      ok: true,
+      dryRun: true,
+      draftPath,
+      branch,
+      commands,
+      message: `Wrote draft to ${relDraft}. Run the printed git/gh commands to open a draft PR.`,
+    }
+  }
+
+  if (!existsSync(join(root, '.git'))) {
+    return {
+      ok: false,
+      dryRun: false,
+      draftPath,
+      branch,
+      commands,
+      message: 'Not a git repository. Commit the draft manually or run with --dry-run.',
+    }
+  }
+
+  if (!hasGh()) {
+    return {
+      ok: false,
+      dryRun: false,
+      draftPath,
+      branch,
+      commands,
+      message: 'GitHub CLI (gh) not found. Install gh or use --dry-run for local draft + commands.',
+    }
+  }
+
+  const auth = run('gh', ['auth', 'status'], root)
+  if (!auth.ok) {
+    return {
+      ok: false,
+      dryRun: false,
+      draftPath,
+      branch,
+      commands,
+      message: `gh is not authenticated. Run: gh auth login\n${auth.out}`,
+    }
+  }
+
+  const checkout = run('git', ['checkout', '-b', branch], root)
+  if (!checkout.ok) {
+    return {
+      ok: false,
+      dryRun: false,
+      draftPath,
+      branch,
+      commands,
+      message: `git checkout failed: ${checkout.out}`,
+    }
+  }
+
+  run('git', ['add', relDraft], root)
+  const commit = run('git', ['commit', '-m', 'draft: doc-bridge memory promotion'], root)
+  if (!commit.ok) {
+    return {
+      ok: false,
+      dryRun: false,
+      draftPath,
+      branch,
+      commands,
+      message: `git commit failed: ${commit.out}`,
+    }
+  }
+
+  const push = run('git', ['push', '-u', 'origin', branch], root)
+  if (!push.ok) {
+    return {
+      ok: false,
+      dryRun: false,
+      draftPath,
+      branch,
+      commands,
+      message: `git push failed: ${push.out}`,
+    }
+  }
+
+  const prArgs = [
+    'pr',
+    'create',
+    '--draft',
+    '--title',
+    draft.title,
+    '--body-file',
+    relDraft,
+    ...(options.base ? ['--base', options.base] : []),
+  ]
+  let prUrl = ''
+  try {
+    prUrl = execFileSync('gh', prArgs, { cwd: root, encoding: 'utf8' }).trim()
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return {
+      ok: false,
+      dryRun: false,
+      draftPath,
+      branch,
+      commands,
+      message: `gh pr create failed: ${message}`,
+    }
+  }
+
+  return {
+    ok: true,
+    dryRun: false,
+    draftPath,
+    branch,
+    prUrl,
+    ...(prUrl ? { previewUrl: prUrl } : {}),
+    commands,
+    message: prUrl ? `Draft PR opened: ${prUrl}` : 'Draft PR created.',
+  }
+}

package/src/playbook/doc-bridge-pattern.ts

@@ -0,0 +1,121 @@
+export const DOC_BRIDGE_PATTERN_ID = 'doc-bridge-pattern' as const
+
+export const DOC_BRIDGE_PATTERN_META = {
+  id: DOC_BRIDGE_PATTERN_ID,
+  title: 'Doc Bridge Pattern',
+  slug: 'pillars/ai-collaboration/doc-bridge-pattern',
+  license: 'CC-BY-4.0',
+  visibility: 'public',
+  playbookUrl: 'https://playbook.agentskit.io/patterns/doc-bridge-pattern',
+  npmPackage: '@agentskit/doc-bridge',
+  cli: 'ak-docs',
+} as const
+
+export const docBridgePatternMarkdown = (): string => `---
+type: pattern
+id: ${DOC_BRIDGE_PATTERN_ID}
+purpose: Route coding agents to the correct package, checks, and human docs in any monorepo.
+owner: AgentsKit
+license: CC-BY-4.0
+visibility: public
+tags: [agents, documentation, monorepo, handoff, mcp]
+---
+
+# Doc Bridge Pattern
+
+**AgentHandoff for your monorepo** — deterministic routing so agents edit the right roots, run the right checks, and stay linked to human documentation.
+
+## Problem
+
+Coding agents guess package ownership. They edit sibling modules, run repo-wide tests, and ship changes without a bridge to human-facing guides. Wikis and RAG explain concepts but weakly answer *where to act*.
+
+## Solution (three artifacts)
+
+| Artifact | Role |
+|----------|------|
+| **AgentHandoff** | JSON handoff: \`startHere\`, \`editRoots\`, \`checks\`, \`humanDoc\`, \`bridge\` |
+| **DocBridgeIndex** | Deterministic index + \`contentHash\` for CI freshness gates |
+| **Self-describe** | \`llms.txt\`, \`capabilities.json\` for discovery |
+
+## Four loops
+
+| Loop | Command | Outcome |
+|------|---------|---------|
+| **Act** | \`ak-docs query package <id> --agent\` | Agent edits only \`editRoots\` |
+| **Bridge** | \`ak-docs bootstrap agent-docs\` | Link agent corpus ↔ human site |
+| **Learn** | \`ak-docs memory promote --pr\` | HITL draft PR from agent memory |
+| **Explain** | \`ak-docs ask "<question>"\` | Local consult + handoff preview |
+
+## 60-second proof
+
+\`\`\`bash
+npm i -D @agentskit/doc-bridge
+npx ak-docs demo --text
+ak-docs mcp install --cursor
+\`\`\`
+
+## AgentHandoff example
+
+\`\`\`json
+{
+  "type": "agent-handoff",
+  "startHere": "docs/for-agents/packages/auth.md",
+  "editRoots": ["packages/auth"],
+  "checks": ["pnpm --filter @demo/auth test"],
+  "humanDoc": "/docs/guides/auth",
+  "bridge": { "humanDoc": "linked" }
+}
+\`\`\`
+
+When \`humanDoc\` is missing, handoffs surface \`bridge.action: "ak-docs bootstrap agent-docs"\` — a feature, not a silent gap.
+
+## MCP contract
+
+Agents call \`handoff.resolve\` before editing \`packages/*\`:
+
+1. Read \`startHere\`
+2. Stay inside \`editRoots\`
+3. Run every \`checks\` command
+4. Link \`humanDoc\` or escalate missing bridge
+
+## CI gate
+
+\`\`\`yaml
+- uses: AgentsKit-io/doc-bridge@v1.0.0
+\`\`\`
+
+Or: \`ak-docs index && ak-docs gate run\` — stale index fails the PR.
+
+## Coverage metric
+
+\`\`\`bash
+ak-docs doctor --text
+ak-docs doctor --badge
+\`\`\`
+
+Teams track handoff % and human-bridge % daily.
+
+## When to use
+
+- pnpm/npm monorepos with real package ownership
+- Fumadocus / Docusaurus human sites + dense agent corpus
+- Cursor / Claude / Codex agents that should not guess edit roots
+
+## When not to use
+
+- Single-file repos with no ownership boundaries (AGENTS.md may suffice)
+- Hosted doc chat as primary product (doc-bridge is routing + bridge, not SaaS chat)
+
+## References
+
+- npm: https://www.npmjs.com/package/@agentskit/doc-bridge
+- repo: https://github.com/AgentsKit-io/doc-bridge
+- skill: https://github.com/AgentsKit-io/doc-bridge/blob/master/docs/skills/doc-bridge.md
+- landing: https://agentskit-io.github.io/doc-bridge/
+`
+
+export const docBridgePatternPayload = () => ({
+  ...DOC_BRIDGE_PATTERN_META,
+  format: 'okf-pattern-v1',
+  body: docBridgePatternMarkdown(),
+})

package/src/query/query.ts

@@ -32,6 +32,18 @@ const handoffForPackage = (
   const owner = index.lookup?.ownership?.[id]
   if (!owner) throw new Error(`Unknown package/ownership id "${id}". Try: ak-docs list packages`)
 
+  const bridge = owner.humanDoc
+    ? /^https?:\/\//.test(owner.humanDoc)
+      ? { humanDoc: 'external' as const }
+      : { humanDoc: 'linked' as const }
+    : config.corpus.human
+      ? {
+          humanDoc: 'missing' as const,
+          action: 'ak-docs bootstrap agent-docs',
+          bootstrap: `docs/for-agents/human/${id}.md`,
+        }
+      : undefined
+
   return normalizeAgentHandoff({
     type: 'agent-handoff',
     source: config.index?.outFile ?? '.doc-bridge/index.json',
@@ -47,7 +59,13 @@ const handoffForPackage = (
     editRoots: [owner.path],
     checks: [...owner.checks],
     ...(owner.humanDoc ? { humanDoc: owner.humanDoc } : {}),
-    notes: owner.purpose ? [owner.purpose] : [],
+    ...(bridge ? { bridge } : {}),
+    notes: [
+      ...(owner.purpose ? [owner.purpose] : []),
+      ...(!owner.humanDoc && config.corpus.human
+        ? [`Human guide missing for ${id}. Run: ak-docs bootstrap agent-docs`]
+        : []),
+    ],
   })
 }
 

package/src/query/search.ts

@@ -11,23 +11,80 @@ export type SearchMatch = {
 const tokenize = (value: string): string[] =>
   value
     .toLowerCase()
-    .split(/[^a-z0-9]+/)
+    .split(/[^a-z0-9@/_-]+/)
     .filter((t) => t.length >= 2)
 
+const PACKAGE_INTENT =
+  /\b(package|module|pkg|edit|change|where|owns?|ownership|handoff|start)\b/i
+
+const scoreHay = (tokens: readonly string[], hay: string, weight = 1): number => {
+  let score = 0
+  for (const token of tokens) {
+    if (!hay.includes(token)) continue
+    score += token.length * weight
+    // whole-word-ish bonus
+    if (new RegExp(`(?:^|[^a-z0-9])${token}(?:[^a-z0-9]|$)`).test(hay)) {
+      score += token.length
+    }
+  }
+  return score
+}
+
+/** Exact / near-exact identity boost so "core" ranks the core package over mentions of @agentskit/core. */
+const identityBoost = (id: string, path: string, tokens: readonly string[], term: string): number => {
+  const idLower = id.toLowerCase()
+  const termLower = term.toLowerCase().trim()
+  const base = path.split('/').pop()?.replace(/\.mdx?$/i, '').toLowerCase() ?? ''
+  let boost = 0
+
+  if (idLower === termLower || base === termLower) boost += 200
+  if (tokens.length === 1 && (idLower === tokens[0] || base === tokens[0])) boost += 200
+
+  for (const token of tokens) {
+    if (idLower === token) boost += 120
+    else if (idLower.startsWith(`${token}-`) || idLower.endsWith(`-${token}`)) boost += 40
+    else if (idLower.includes(token) && idLower.length <= token.length + 4) boost += 30
+    if (base === token) boost += 100
+  }
+
+  // Prefer short ids when term is the id (package name)
+  if (tokens.includes(idLower)) boost += Math.max(0, 40 - idLower.length)
+
+  return boost
+}
+
+const preferOwnership = (term: string): boolean =>
+  PACKAGE_INTENT.test(term) || /^(where|how).*(edit|change|package|module)/i.test(term)
+
 export const searchIndex = (index: DocBridgeIndexV1, term: string, limit = 20): SearchMatch[] => {
   const tokens = tokenize(term)
   if (!tokens.length) return []
 
-  const matches: SearchMatch[] = []
+  const wantOwnership = preferOwnership(term)
+  const byPath = new Map<string, SearchMatch>()
 
-  for (const entry of index.knowledge) {
-    const hay = `${entry.id} ${entry.title} ${entry.description ?? ''} ${entry.path}`.toLowerCase()
-    let score = 0
-    for (const token of tokens) {
-      if (hay.includes(token)) score += token.length
+  const consider = (match: SearchMatch) => {
+    const key = match.path
+    const existing = byPath.get(key)
+    if (!existing) {
+      byPath.set(key, match)
+      return
     }
+    // Prefer ownership over knowledge for same path; else higher score
+    const prefer =
+      match.score > existing.score ||
+      (match.score === existing.score && match.type === 'ownership' && existing.type !== 'ownership') ||
+      (wantOwnership && match.type === 'ownership' && existing.type !== 'ownership' && match.score >= existing.score - 20)
+    if (prefer) byPath.set(key, match)
+  }
+
+  for (const entry of index.knowledge) {
+    const body = (entry as { body?: string }).body ?? ''
+    const hay = `${entry.id} ${entry.title} ${entry.description ?? ''} ${entry.path} ${body}`.toLowerCase()
+    let score = scoreHay(tokens, hay, 1)
+    score += identityBoost(entry.id, entry.path, tokens, term)
     if (score > 0) {
-      matches.push({
+      consider({
         type: 'knowledge',
         id: entry.id,
         path: entry.path,
@@ -38,21 +95,32 @@ export const searchIndex = (index: DocBridgeIndexV1, term: string, limit = 20):
   }
 
   for (const [id, owner] of Object.entries(index.lookup?.ownership ?? {})) {
-    const hay = `${id} ${owner.path} ${owner.purpose ?? ''} ${owner.group ?? ''}`.toLowerCase()
-    let score = 0
-    for (const token of tokens) {
-      if (hay.includes(token)) score += token.length * 2
-    }
+    const path = owner.agentDoc ?? owner.path
+    const hay = `${id} ${owner.path} ${owner.purpose ?? ''} ${owner.group ?? ''} ${owner.agentDoc ?? ''} ${owner.humanDoc ?? ''}`.toLowerCase()
+    let score = scoreHay(tokens, hay, 2)
+    score += identityBoost(id, path, tokens, term)
+    // Ownership is primary for routing questions
+    if (wantOwnership) score += 25
+    score += 15 // slight base preference for actionable ownership targets
     if (score > 0) {
-      matches.push({
+      consider({
         type: 'ownership',
         id,
-        path: owner.agentDoc ?? owner.path,
+        path,
         ...(owner.purpose ? { summary: owner.purpose } : {}),
         score,
       })
     }
   }
 
-  return matches.sort((a, b) => b.score - a.score).slice(0, limit)
-}
+  return [...byPath.values()].sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score
+    // Tie-break: exact id match, then ownership, then shorter id
+    const aExact = tokens.includes(a.id.toLowerCase()) ? 1 : 0
+    const bExact = tokens.includes(b.id.toLowerCase()) ? 1 : 0
+    if (bExact !== aExact) return bExact - aExact
+    if (a.type === 'ownership' && b.type !== 'ownership') return -1
+    if (b.type === 'ownership' && a.type !== 'ownership') return 1
+    return a.id.localeCompare(b.id)
+  }).slice(0, limit)
+}

package/src/schemas/agent-handoff.ts

@@ -28,6 +28,16 @@ export const HandoffTargetSchema = z
 
 export type HandoffTarget = z.infer<typeof HandoffTargetSchema>
 
+export const HandoffBridgeSchema = z
+  .object({
+    humanDoc: z.enum(['linked', 'missing', 'external']),
+    action: z.string().min(1).max(256).optional(),
+    bootstrap: z.string().min(1).max(256).optional(),
+  })
+  .strict()
+
+export type HandoffBridge = z.infer<typeof HandoffBridgeSchema>
+
 /** v1 — canonical AgentHandoff. Legacy payloads may omit schemaVersion. */
 export const AgentHandoffV1Schema = z
   .object({
@@ -40,6 +50,7 @@ export const AgentHandoffV1Schema = z
     editRoots: z.array(z.string().min(1).max(512)).max(32),
     checks: z.array(z.string().min(1).max(256)).max(32),
     humanDoc: z.string().min(1).max(512).nullable().optional(),
+    bridge: HandoffBridgeSchema.optional(),
     playbookPatterns: z.array(z.string().url()).max(16).optional(),
     notes: z.array(z.string().min(1).max(1024)).max(16),
   })

package/src/schemas/doc-bridge-index.ts

@@ -21,7 +21,9 @@ export const KnowledgeEntrySchema = z
     type: z.string().min(1).max(128),
     title: z.string().min(1).max(256),
     path: z.string().min(1).max(512),
-    description: z.string().max(1024).optional(),
+    description: z.string().max(2_048).optional(),
+    /** Flattened body excerpt for full-text search (not for display). */
+    body: z.string().max(8_000).optional(),
     links: z.array(z.string().min(1).max(512)).max(64).optional(),
     tags: z.array(z.string().min(1).max(64)).max(32).optional(),
   })

package/src/schemas/json-schemas.ts

@@ -121,7 +121,8 @@ export const DocBridgeIndexV1JsonSchema = {
           type: { type: 'string', minLength: 1, maxLength: 128 },
           title: { type: 'string', minLength: 1, maxLength: 256 },
           path: { type: 'string', minLength: 1, maxLength: 512 },
-          description: { type: 'string', maxLength: 1024 },
+          description: { type: 'string', maxLength: 2048 },
+          body: { type: 'string', maxLength: 8000 },
           links: stringArray(64),
           tags: stringArray(32),
         },

package/src/version.ts

@@ -1 +1 @@
-export const PACKAGE_VERSION = '0.1.0-alpha.2'
+export const PACKAGE_VERSION = '1.0.0'