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

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'