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

package/src/doctor/run-doctor.ts

@@ -0,0 +1,286 @@
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import { buildDocBridgeIndex } from '../index-builder/build-index.js'
+import { scanAgentCorpus } from '../index-builder/scan-corpus.js'
+import { runGates, type GateRunResult } from '../gates/run-gates.js'
+import { IndexNotFoundError, loadDocBridgeIndex } from '../query/load-index.js'
+import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
+import { doctorBadgeMetrics, type DoctorBadgeMetrics } from './badge.js'
+
+export type DoctorIssue = {
+  readonly severity: 'error' | 'warn' | 'info'
+  readonly code: string
+  readonly message: string
+  readonly action?: string
+}
+
+export type DoctorCoverage = {
+  readonly packages: {
+    readonly total: number
+    readonly withAgentDoc: number
+    readonly withHumanDoc: number
+    readonly missingAgentDoc: readonly string[]
+    readonly missingHumanDoc: readonly string[]
+  }
+  readonly agentDocs: {
+    readonly total: number
+    readonly indexed: number
+    readonly unindexed: readonly string[]
+  }
+  readonly freshness: {
+    readonly ok: boolean
+    readonly message: string
+    readonly hasIndex: boolean
+  }
+  readonly gates: GateRunResult
+}
+
+export type DoctorReport = {
+  readonly ok: boolean
+  readonly score: number
+  readonly grade: 'A' | 'B' | 'C' | 'D' | 'F'
+  readonly coverage: DoctorCoverage
+  readonly badge: DoctorBadgeMetrics
+  readonly issues: readonly DoctorIssue[]
+  readonly nextActions: readonly string[]
+}
+
+const gradeForScore = (score: number): DoctorReport['grade'] => {
+  if (score >= 90) return 'A'
+  if (score >= 75) return 'B'
+  if (score >= 60) return 'C'
+  if (score >= 40) return 'D'
+  return 'F'
+}
+
+const agentDocPaths = (index: DocBridgeIndexV1): Set<string> => {
+  const paths = new Set<string>()
+  for (const owner of Object.values(index.lookup?.ownership ?? {})) {
+    if (owner.agentDoc) paths.add(owner.agentDoc)
+  }
+  for (const handoff of Object.values(index.handoffs ?? {})) {
+    if (handoff.startHere) paths.add(handoff.startHere)
+  }
+  return paths
+}
+
+const computeScore = (coverage: DoctorCoverage): number => {
+  let score = 0
+
+  if (coverage.freshness.hasIndex) score += 15
+  if (coverage.freshness.ok) score += 15
+
+  const { total, withAgentDoc, withHumanDoc } = coverage.packages
+  if (total > 0) {
+    score += Math.round((withAgentDoc / total) * 35)
+    score += Math.round((withHumanDoc / total) * 20)
+  } else if (coverage.agentDocs.indexed > 0) {
+    score += 35
+  }
+
+  if (coverage.gates.ok) score += 15
+  else {
+    const passed = coverage.gates.results.filter((gate) => gate.ok).length
+    const totalGates = coverage.gates.results.length || 1
+    score += Math.round((passed / totalGates) * 10)
+  }
+
+  return Math.min(100, Math.max(0, score))
+}
+
+const buildIssues = (coverage: DoctorCoverage): DoctorIssue[] => {
+  const issues: DoctorIssue[] = []
+
+  if (!coverage.freshness.hasIndex) {
+    issues.push({
+      severity: 'error',
+      code: 'index-missing',
+      message: 'No doc-bridge index found.',
+      action: 'ak-docs index',
+    })
+  } else if (!coverage.freshness.ok) {
+    issues.push({
+      severity: 'error',
+      code: 'index-stale',
+      message: coverage.freshness.message,
+      action: 'ak-docs index',
+    })
+  }
+
+  for (const id of coverage.packages.missingAgentDoc) {
+    issues.push({
+      severity: 'warn',
+      code: 'missing-agent-doc',
+      message: `Package "${id}" has no dedicated agent doc.`,
+      action: `ak-docs init --scaffold-workspaces  # or edit docs/for-agents/packages/${id}.md`,
+    })
+  }
+
+  for (const id of coverage.packages.missingHumanDoc) {
+    issues.push({
+      severity: 'info',
+      code: 'missing-human-doc',
+      message: `Package "${id}" has no linked human guide.`,
+      action: 'ak-docs bootstrap agent-docs',
+    })
+  }
+
+  for (const gate of coverage.gates.results.filter((result) => !result.ok)) {
+    issues.push({
+      severity: gate.id === 'index-freshness' ? 'error' : 'warn',
+      code: `gate-${gate.id}`,
+      message: gate.message,
+      action: gate.id === 'index-freshness' ? 'ak-docs index' : 'ak-docs gate run',
+    })
+  }
+
+  return issues
+}
+
+const buildNextActions = (issues: readonly DoctorIssue[], coverage: DoctorCoverage): string[] => {
+  const actions = new Set<string>()
+  for (const issue of issues) {
+    if (issue.action) actions.add(issue.action)
+  }
+
+  if (!coverage.freshness.hasIndex || !coverage.freshness.ok) {
+    actions.add('ak-docs index')
+  }
+  if (coverage.packages.missingHumanDoc.length) {
+    actions.add('ak-docs bootstrap agent-docs')
+  }
+  if (coverage.packages.total > 0) {
+    const sample =
+      coverage.packages.missingAgentDoc[0] ??
+      coverage.packages.missingHumanDoc[0]
+    if (sample) actions.add(`ak-docs query package ${sample} --agent`)
+  }
+  if (!actions.size) {
+    actions.add('ak-docs mcp install --cursor')
+    actions.add('ak-docs gate run')
+  }
+
+  return [...actions].slice(0, 6)
+}
+
+export const runDoctor = (root: string, config: DocBridgeConfigV1): DoctorReport => {
+  let index: DocBridgeIndexV1 | undefined
+  let hasIndex = true
+  let freshnessOk = false
+  let freshnessMessage = 'Index is fresh'
+
+  try {
+    index = loadDocBridgeIndex(root, config)
+    const next = buildDocBridgeIndex({ root, config, write: false }).index.contentHash
+    freshnessOk = index.contentHash === next
+    freshnessMessage = freshnessOk ? 'Index is fresh' : 'Index is stale. Run: ak-docs index'
+  } catch (error) {
+    if (error instanceof IndexNotFoundError) {
+      hasIndex = false
+      freshnessOk = false
+      freshnessMessage = error.message
+      index = buildDocBridgeIndex({ root, config, write: false }).index
+    } else {
+      throw error
+    }
+  }
+
+  const ownership = Object.entries(index.lookup?.ownership ?? {})
+  const missingAgentDoc = ownership
+    .filter(([, owner]) => !owner.agentDoc || owner.agentDoc === config.corpus.agent.index)
+    .map(([id]) => id)
+  const missingHumanDoc = ownership.filter(([, owner]) => !owner.humanDoc).map(([id]) => id)
+
+  const indexedPaths = new Set(index.knowledge.map((entry) => entry.path))
+  const expectedAgentDocs = agentDocPaths(index)
+  const unindexed = [...expectedAgentDocs].filter((path) => !indexedPaths.has(path))
+
+  const corpusDocs = scanAgentCorpus(root, config).filter(
+    (doc) => doc.path !== config.corpus.agent.index,
+  )
+
+  const gates = runGates(root, config)
+
+  const coverage: DoctorCoverage = {
+    packages: {
+      total: ownership.length,
+      withAgentDoc: ownership.length - missingAgentDoc.length,
+      withHumanDoc: ownership.length - missingHumanDoc.length,
+      missingAgentDoc,
+      missingHumanDoc,
+    },
+    agentDocs: {
+      total: corpusDocs.length,
+      indexed: corpusDocs.filter((doc) => indexedPaths.has(doc.path)).length,
+      unindexed: corpusDocs.filter((doc) => !indexedPaths.has(doc.path)).map((doc) => doc.path),
+    },
+    freshness: {
+      ok: freshnessOk,
+      message: freshnessMessage,
+      hasIndex,
+    },
+    gates,
+  }
+
+  const issues = buildIssues(coverage)
+  const score = computeScore(coverage)
+  const nextActions = buildNextActions(issues, coverage)
+
+  const report: DoctorReport = {
+    ok: issues.every((issue) => issue.severity !== 'error') && gates.ok,
+    score,
+    grade: gradeForScore(score),
+    coverage,
+    badge: { handoffPct: 0, bridgePct: 0, score, grade: gradeForScore(score), packages: 0 },
+    issues,
+    nextActions,
+  }
+  return { ...report, badge: doctorBadgeMetrics(report) }
+}
+
+export const formatDoctorText = (report: DoctorReport): string[] => {
+  const { coverage } = report
+  const handoffPct =
+    coverage.packages.total > 0
+      ? Math.round((coverage.packages.withAgentDoc / coverage.packages.total) * 100)
+      : 0
+  const humanPct =
+    coverage.packages.total > 0
+      ? Math.round((coverage.packages.withHumanDoc / coverage.packages.total) * 100)
+      : 0
+
+  const lines = [
+    'doc-bridge doctor',
+    '─'.repeat(40),
+    `Score: ${report.score}/100 (${report.grade})`,
+    '',
+    'Coverage',
+    `  Packages:        ${coverage.packages.total}`,
+    `  Agent docs:      ${coverage.packages.withAgentDoc}/${coverage.packages.total} (${handoffPct}% handoff-ready)`,
+    `  Human guides:    ${coverage.packages.withHumanDoc}/${coverage.packages.total} (${humanPct}% bridged)`,
+    `  Corpus indexed:  ${coverage.agentDocs.indexed}/${coverage.agentDocs.total} agent docs`,
+    `  Index freshness: ${coverage.freshness.ok ? 'fresh' : 'stale or missing'}`,
+    `  Gates:           ${coverage.gates.results.filter((g) => g.ok).length}/${coverage.gates.results.length} passing`,
+    `  Badge:           handoff ${report.badge.handoffPct}% · bridge ${report.badge.bridgePct}%`,
+  ]
+
+  if (coverage.packages.missingHumanDoc.length) {
+    lines.push('', 'Missing humanDoc (bridge gap)', ...coverage.packages.missingHumanDoc.map((id) => `  • ${id}`))
+  }
+  if (coverage.packages.missingAgentDoc.length) {
+    lines.push('', 'Missing agent doc', ...coverage.packages.missingAgentDoc.map((id) => `  • ${id}`))
+  }
+
+  if (report.issues.length) {
+    lines.push('', 'Issues')
+    for (const issue of report.issues.slice(0, 8)) {
+      const icon = issue.severity === 'error' ? '✗' : issue.severity === 'warn' ? '!' : '·'
+      lines.push(`  ${icon} [${issue.code}] ${issue.message}`)
+    }
+    if (report.issues.length > 8) {
+      lines.push(`  … +${report.issues.length - 8} more`)
+    }
+  }
+
+  lines.push('', 'Next actions', ...report.nextActions.map((action) => `  → ${action}`))
+  return lines
+}

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/intelligence/adapter.ts

@@ -9,6 +9,19 @@ const readEnv = (name: string | undefined): string | undefined => {
   return value && value.length > 0 ? value : undefined
 }
 
+const providerDefaultApiKeyEnv = (provider: string): string | undefined => {
+  switch (provider) {
+    case 'openai':
+      return 'OPENAI_API_KEY'
+    case 'anthropic':
+      return 'ANTHROPIC_API_KEY'
+    case 'openrouter':
+      return 'OPENROUTER_API_KEY'
+    default:
+      return undefined
+  }
+}
+
 export type ResolvedIntelligence = {
   readonly adapter: unknown
   readonly embed: unknown
@@ -30,7 +43,7 @@ export const resolveIntelligenceRuntime = async (
   const adapters = await importPeer<typeof import('@agentskit/adapters')>('@agentskit/adapters')
   const provider = adapterCfg.provider
   const model = adapterCfg.model
-  const apiKey = readEnv(adapterCfg.apiKeyEnv) ?? readEnv('OPENAI_API_KEY') ?? readEnv('ANTHROPIC_API_KEY')
+  const apiKey = readEnv(adapterCfg.apiKeyEnv) ?? readEnv(providerDefaultApiKeyEnv(provider))
   const baseUrl = adapterCfg.baseUrl
 
   let adapter: unknown

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)