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

package/src/index-builder/build-handoffs.ts

@@ -183,6 +183,18 @@ export const buildLookup = (
     }
     ownership[pkg.id] = record
 
+    const bridge = record.humanDoc
+      ? /^https?:\/\//.test(record.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/${pkg.id}.md`,
+          }
+        : undefined
+
     handoffs[pkg.id] = {
       type: 'agent-handoff',
       schemaVersion: 1,
@@ -201,7 +213,13 @@ export const buildLookup = (
       editRoots: [record.path],
       checks: [...record.checks],
       ...(record.humanDoc ? { humanDoc: record.humanDoc } : {}),
-      notes: record.purpose ? [record.purpose] : [],
+      ...(bridge ? { bridge } : {}),
+      notes: [
+        ...(record.purpose ? [record.purpose] : []),
+        ...(!record.humanDoc && config.corpus.human
+          ? [`Human guide missing for ${pkg.id}. Run: ak-docs bootstrap agent-docs`]
+          : []),
+      ],
     }
   }
 

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

@@ -0,0 +1,94 @@
+import { existsSync, watch } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import { buildDocBridgeIndex } from './build-index.js'
+
+export type WatchIndexOptions = {
+  readonly root: string
+  readonly config: DocBridgeConfigV1
+  readonly configPath?: string
+  readonly debounceMs?: number
+  readonly onRebuild?: (summary: { knowledgeCount: number; handoffCount: number; hash: string }) => void
+}
+
+const WATCH_PATTERN = /\.(md|mdx|json|ya?ml|mdc)$/i
+
+const collectWatchRoots = (root: string, config: DocBridgeConfigV1, configPath?: string): string[] => {
+  const roots = new Set<string>()
+  roots.add(resolve(root, config.corpus.agent.root))
+  const humanSources = config.corpus.human
+    ? Array.isArray(config.corpus.human)
+      ? config.corpus.human
+      : [config.corpus.human]
+    : []
+  for (const source of humanSources) {
+    const humanOpts = source.options ?? {}
+    for (const key of ['contentDir', 'docsDir', 'root']) {
+      const value = humanOpts[key]
+      if (typeof value === 'string' && value.length) roots.add(resolve(root, value))
+    }
+  }
+  if (configPath) roots.add(dirname(resolve(configPath)))
+  return [...roots].filter((dir) => existsSync(dir))
+}
+
+export const watchDocBridgeIndex = (opts: WatchIndexOptions): Promise<number> => {
+  const debounceMs = opts.debounceMs ?? 350
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let running = false
+
+  const rebuild = (): void => {
+    if (timer) clearTimeout(timer)
+    timer = setTimeout(() => {
+      if (running) return
+      running = true
+      try {
+        const result = buildDocBridgeIndex({ root: opts.root, config: opts.config })
+        const handoffCount = Object.keys(result.index.handoffs ?? {}).length
+        const summary = {
+          knowledgeCount: result.index.knowledge.length,
+          handoffCount,
+          hash: result.index.contentHash.slice(0, 8),
+        }
+        opts.onRebuild?.(summary)
+        process.stdout.write(
+          `[ak-docs] indexed ${summary.knowledgeCount} docs, ${summary.handoffCount} handoffs (${summary.hash}…)\n`,
+        )
+      } catch (error) {
+        process.stderr.write(
+          `[ak-docs] index failed: ${error instanceof Error ? error.message : String(error)}\n`,
+        )
+      } finally {
+        running = false
+      }
+    }, debounceMs)
+  }
+
+  rebuild()
+
+  for (const dir of collectWatchRoots(opts.root, opts.config, opts.configPath)) {
+    watch(dir, { recursive: true }, (_event, filename) => {
+      if (!filename || !WATCH_PATTERN.test(filename)) return
+      rebuild()
+    })
+  }
+
+  const configDir = resolve(opts.root)
+  if (existsSync(configDir)) {
+    watch(configDir, (_event, filename) => {
+      if (!filename || !/doc-bridge\.config/.test(filename)) return
+      rebuild()
+    })
+  }
+
+  process.stdout.write(
+    `[ak-docs] watching ${collectWatchRoots(opts.root, opts.config, opts.configPath).join(', ') || opts.root} (Ctrl+C to stop)\n`,
+  )
+
+  return new Promise((resolvePromise) => {
+    const onSignal = () => resolvePromise(0)
+    process.once('SIGINT', onSignal)
+    process.once('SIGTERM', onSignal)
+  })
+}

package/src/index.ts

@@ -20,7 +20,9 @@ export {
   HandoffTargetTypeSchema,
   HANDOFF_SCHEMA_VERSION,
   normalizeAgentHandoff,
+  HandoffBridgeSchema,
   type AgentHandoffV1,
+  type HandoffBridge,
   type AgentSearchV1,
   type HandoffTarget,
   type HandoffTargetType,
@@ -74,6 +76,22 @@ export {
   type GateRunResult,
 } from './gates/run-gates.js'
 export { MCP_TOOLS, handleMcpRequest, startMcpStdioServer } from './mcp/server.js'
+export { installMcpConfig, mcpSnippet, type McpInstallResult, type McpInstallTarget } from './mcp/install.js'
+export { runDoctor, formatDoctorText, type DoctorReport, type DoctorIssue, type DoctorCoverage } from './doctor/run-doctor.js'
+export {
+  doctorBadgeMetrics,
+  formatDoctorBadgeJson,
+  formatDoctorBadgeMarkdown,
+  type DoctorBadgeMetrics,
+} from './doctor/badge.js'
+export { watchDocBridgeIndex, type WatchIndexOptions } from './index-builder/watch-index.js'
+export {
+  promoteMemoryToGithubPr,
+  writePromotionDraft,
+  defaultPromotionDraftPath,
+  type GithubPrOptions,
+  type GithubPrResult,
+} from './memory/github-pr.js'
 export { sha256NormalizedV1 } from './index-builder/content-hash.js'
 export { IndexNotFoundError, indexFilePath, loadDocBridgeIndex, resolveRoot } from './query/load-index.js'
 export { runQuery, type QueryKind, type QueryRequest, type QueryResult } from './query/query.js'
@@ -118,3 +136,9 @@ export { projectRootFromConfigPath } from './config/load-config.js'
 export { createDocBridgeRag } from './intelligence/rag.js'
 export { runChatOnce, startInkChat } from './intelligence/chat.js'
 export { PeerMissingError, layer1InstallHint } from './intelligence/peers.js'
+export {
+  DOC_BRIDGE_PATTERN_ID,
+  DOC_BRIDGE_PATTERN_META,
+  docBridgePatternMarkdown,
+  docBridgePatternPayload,
+} from './playbook/doc-bridge-pattern.js'

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/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/version.ts

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