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

package/src/config/defaults.ts

@@ -0,0 +1,63 @@
+import type { DocBridgeConfigV1 } from './schema.js'
+
+const DEFAULT_AGENT_EXCLUDE = ['**/node_modules/**', '**/.git/**'] as const
+
+export const applyConfigDefaults = (config: DocBridgeConfigV1): DocBridgeConfigV1 => {
+  const agentRoot = config.corpus.agent.root
+  const agentIndex = config.corpus.agent.index ?? `${agentRoot}/INDEX.md`
+
+  return {
+    ...config,
+    corpus: {
+      ...config.corpus,
+      agent: {
+        ...config.corpus.agent,
+        index: agentIndex,
+        include: config.corpus.agent.include ?? ['**/*.{md,mdx}'],
+        exclude: config.corpus.agent.exclude ?? [...DEFAULT_AGENT_EXCLUDE],
+      },
+    },
+    index: {
+      outFile: '.doc-bridge/index.json',
+      contentHash: 'sha256-normalized-v1',
+      llmsTxt: {
+        enabled: true,
+        outFile: 'llms.txt',
+        ...config.index?.llmsTxt,
+      },
+      capabilities: {
+        enabled: true,
+        outFile: '.doc-bridge/capabilities.json',
+        ...config.index?.capabilities,
+      },
+      ...config.index,
+    },
+    gates: {
+      preset: 'minimal',
+      ...config.gates,
+    },
+    surfaces: {
+      cli: {
+        bin: 'ak-docs',
+        defaultFormat: 'json',
+        ...config.surfaces?.cli,
+      },
+      mcp: {
+        enabled: true,
+        tools: ['handoff.resolve', 'doc.search', 'doc.get', 'gate.status'],
+        transport: 'stdio',
+        ...config.surfaces?.mcp,
+      },
+      ...config.surfaces,
+    },
+    intelligence: config.intelligence
+      ? {
+          enabled: false,
+          ...config.intelligence,
+          chat: config.intelligence.chat
+            ? { handoffFirst: true, ...config.intelligence.chat }
+            : undefined,
+        }
+      : { enabled: false },
+  }
+}

package/src/config/define-config.ts

@@ -0,0 +1,6 @@
+import { applyConfigDefaults } from './defaults.js'
+import { DocBridgeConfigV1Schema, type DocBridgeConfigV1 } from './schema.js'
+
+/** Type-safe config helper for `doc-bridge.config.ts`. */
+export const defineConfig = (config: DocBridgeConfigV1): DocBridgeConfigV1 =>
+  applyConfigDefaults(DocBridgeConfigV1Schema.parse(config))

package/src/config/index.ts

@@ -0,0 +1,15 @@
+export { defineConfig } from './define-config.js'
+export { applyConfigDefaults } from './defaults.js'
+export {
+  loadConfig,
+  resolveProjectRoot,
+  projectRootFromConfigPath,
+  ConfigNotFoundError,
+} from './load-config.js'
+export {
+  DocBridgeConfigV1Schema,
+  AgentCorpusConfigSchema,
+  HumanCorpusConfigSchema,
+  type DocBridgeConfigV1,
+  type AgentCorpusConfig,
+} from './schema.js'

package/src/config/load-config.ts

@@ -0,0 +1,138 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { basename, dirname, join, resolve } from 'node:path'
+import vm from 'node:vm'
+
+import { applyConfigDefaults } from './defaults.js'
+import { DocBridgeConfigV1Schema, type DocBridgeConfigV1 } from './schema.js'
+
+const CONFIG_CANDIDATES = [
+  'doc-bridge.config.ts',
+  'doc-bridge.config.mts',
+  'doc-bridge.config.js',
+  'doc-bridge.config.mjs',
+  'doc-bridge.config.json',
+  'doc-bridge.config.yaml',
+  'doc-bridge.config.yml',
+  'package.json',
+] as const
+
+export type LoadConfigOptions = {
+  readonly cwd?: string
+  readonly explicitPath?: string
+}
+
+export type LoadConfigResult = {
+  readonly config: DocBridgeConfigV1
+  readonly path: string
+}
+
+export class ConfigNotFoundError extends Error {
+  constructor(readonly cwd: string) {
+    super(
+      `No doc-bridge config found in ${cwd}. Run: ak-docs init — or pass --config <path>.`,
+    )
+    this.name = 'ConfigNotFoundError'
+  }
+}
+
+const findConfigPath = (cwd: string, explicitPath?: string): string | null => {
+  if (explicitPath) {
+    const abs = resolve(cwd, explicitPath)
+    return existsSync(abs) ? abs : null
+  }
+  for (const name of CONFIG_CANDIDATES) {
+    const candidate = join(cwd, name)
+    if (!existsSync(candidate)) continue
+    if (name !== 'package.json') return candidate
+    const pkg = parseJsonConfig(readFileSync(candidate, 'utf8'), candidate) as { docBridge?: unknown }
+    if (pkg.docBridge) return candidate
+  }
+  return null
+}
+
+const parseJsonConfig = (raw: string, path: string): unknown => {
+  try {
+    return JSON.parse(raw) as unknown
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new Error(`Failed to parse JSON config at ${path}: ${message}`)
+  }
+}
+
+const parseCodeConfig = (raw: string, path: string): unknown => {
+  const code = raw
+    .replace(/import\s+type\s+[\s\S]*?;?\n/g, '')
+    .replace(/import\s+\{\s*defineConfig\s*\}\s+from\s+['"]@agentskit\/doc-bridge(?:\/config)?['"];?\n?/g, '')
+    .replace(/\s+satisfies\s+[A-Za-z0-9_.$<>{}\[\],\s]+(?=\s*(?:;|\)|$))/g, '')
+    .replace(/export\s+default/, 'module.exports.default =')
+
+  if (/\bimport\b/.test(code)) {
+    throw new Error(`Unsupported import in ${path}. Static config only supports defineConfig imports.`)
+  }
+
+  const sandbox = {
+    module: { exports: {} as { default?: unknown } },
+    exports: {},
+    defineConfig: (config: unknown) => config,
+  }
+  try {
+    vm.runInNewContext(code, sandbox, { timeout: 250, filename: path })
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new Error(`Failed to load config at ${path}: ${message}`)
+  }
+  return sandbox.module.exports.default
+}
+
+const parseConfig = (input: unknown): DocBridgeConfigV1 => {
+  const result = DocBridgeConfigV1Schema.safeParse(input)
+  if (result.success) return result.data
+  throw new Error(
+    `Invalid doc-bridge config:\n${result.error.issues.map((issue) =>
+      `  - ${issue.path.join('.') || '(root)'}: ${issue.message}`,
+    ).join('\n')}`,
+  )
+}
+
+/** v0.1 — static JS/TS config, JSON config files, and package.json#docBridge. */
+export const loadConfig = (opts: LoadConfigOptions = {}): LoadConfigResult => {
+  const cwd = resolve(opts.cwd ?? process.cwd())
+  const path = findConfigPath(cwd, opts.explicitPath)
+  if (!path) throw new ConfigNotFoundError(cwd)
+
+  const raw = readFileSync(path, 'utf8')
+  const ext = path.split('.').pop()?.toLowerCase()
+  if (ext === 'yaml' || ext === 'yml') {
+    throw new Error(`YAML config is not supported yet (${path}). Use doc-bridge.config.json for now.`)
+  }
+
+  const parsed =
+    basename(path) === 'package.json'
+      ? (parseJsonConfig(raw, path) as { docBridge?: unknown }).docBridge
+      : ext === 'ts' || ext === 'mts' || ext === 'js' || ext === 'mjs'
+        ? parseCodeConfig(raw, path)
+      : parseJsonConfig(raw, path)
+  const config = applyConfigDefaults(parseConfig(parsed))
+  return { config, path }
+}
+
+export const resolveProjectRoot = (start = process.cwd()): string => {
+  let cur = resolve(start)
+  for (let i = 0; i < 12; i += 1) {
+    if (findConfigPath(cur)) return cur
+    const parent = dirname(cur)
+    if (parent === cur) break
+    cur = parent
+  }
+  return resolve(start)
+}
+
+/** Project root for a loaded config file path (directory of the config). */
+export const projectRootFromConfigPath = (
+  configFilePath: string,
+  projectRootField?: string,
+): string => {
+  const configDir = dirname(resolve(configFilePath))
+  if (projectRootField) return resolve(configDir, projectRootField)
+  return configDir
+}

package/src/config/schema.ts

@@ -0,0 +1,294 @@
+import { z } from 'zod'
+
+export const CONFIG_SCHEMA_VERSION = 1 as const
+
+export const HumanCorpusPluginIdSchema = z.enum([
+  'plain-markdown',
+  'fumadocs',
+  'docusaurus',
+  'mkdocs',
+  'vitepress',
+  'custom',
+])
+
+export const AgentCorpusConfigSchema = z
+  .object({
+    root: z.string().min(1).max(512),
+    index: z.string().min(1).max(512).optional(),
+    include: z.array(z.string().min(1).max(256)).max(64).optional(),
+    exclude: z.array(z.string().min(1).max(256)).max(64).optional(),
+    okf: z
+      .object({
+        requireType: z.boolean().optional(),
+        allowedTypes: z.array(z.string().min(1).max(128)).max(64).optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict()
+
+export const HumanCorpusConfigSchema = z
+  .object({
+    plugin: HumanCorpusPluginIdSchema,
+    options: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict()
+
+export const IndexConfigSchema = z
+  .object({
+    outFile: z.string().min(1).max(512).optional(),
+    llmsTxt: z
+      .object({
+        enabled: z.boolean().optional(),
+        outFile: z.string().min(1).max(512).optional(),
+        preamble: z.string().max(4_000).optional(),
+      })
+      .strict()
+      .optional(),
+    capabilities: z
+      .object({
+        enabled: z.boolean().optional(),
+        outFile: z.string().min(1).max(512).optional(),
+      })
+      .strict()
+      .optional(),
+    contentHash: z.literal('sha256-normalized-v1').optional(),
+  })
+  .strict()
+
+export const OwnershipEntrySchema = z
+  .object({
+    path: z.string().min(1).max(512),
+    group: z.string().min(1).max(128).optional(),
+    layer: z.string().min(1).max(32).optional(),
+    purpose: z.string().max(1024).optional(),
+    checks: z.array(z.string().min(1).max(256)).max(32).optional(),
+    agentDoc: z.string().min(1).max(512).optional(),
+    humanDoc: z.string().min(1).max(512).optional(),
+  })
+  .strict()
+
+export const RoutingConfigSchema = z
+  .object({
+    plugin: z
+      .enum(['pnpm-monorepo', 'npm-workspaces', 'yarn-workspaces', 'pattern-files', 'custom'])
+      .optional(),
+    options: z
+      .object({
+        packages: z.array(z.string().min(1).max(256)).max(128).optional(),
+        /** Infer ownership from corpus paths/frontmatter (default true). */
+        ownershipFromCorpus: z.boolean().optional(),
+        ownership: z.record(z.string().min(1).max(256), OwnershipEntrySchema).optional(),
+        intents: z
+          .array(
+            z
+              .object({
+                id: z.string().min(1).max(128),
+                title: z.string().min(1).max(256),
+                paths: z.array(z.string().min(1).max(512)).max(32),
+              })
+              .strict(),
+          )
+          .max(128)
+          .optional(),
+        changes: z
+          .array(
+            z
+              .object({
+                id: z.string().min(1).max(128),
+                title: z.string().min(1).max(256),
+                startHere: z.string().min(1).max(512),
+                relatedPackages: z.array(z.string().min(1).max(256)).max(32).optional(),
+              })
+              .strict(),
+          )
+          .max(128)
+          .optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict()
+
+export const GatesConfigSchema = z
+  .object({
+    /** minimal: freshness · standard: + human links · strict: + okf-type · playbook: freshness + okf soft style */
+    preset: z.enum(['minimal', 'standard', 'strict', 'playbook']).optional(),
+    include: z
+      .array(
+        z.enum([
+          'index-freshness',
+          'human-guide-links',
+          'link-rot',
+          'okf-type',
+          'docs-style',
+          'routing-currency',
+          'bootstrap-size',
+        ]),
+      )
+      .max(16)
+      .optional(),
+    exclude: z
+      .array(
+        z.enum([
+          'index-freshness',
+          'human-guide-links',
+          'link-rot',
+          'okf-type',
+          'docs-style',
+          'routing-currency',
+          'bootstrap-size',
+        ]),
+      )
+      .max(16)
+      .optional(),
+    options: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict()
+
+export const SurfacesConfigSchema = z
+  .object({
+    cli: z
+      .object({
+        bin: z.string().min(1).max(64).optional(),
+        defaultFormat: z.enum(['json', 'text']).optional(),
+      })
+      .strict()
+      .optional(),
+    mcp: z
+      .object({
+        enabled: z.boolean().optional(),
+        tools: z
+          .array(
+            z.enum([
+              'handoff.resolve',
+              'doc.search',
+              'doc.get',
+              'gate.status',
+              'playbook.pattern.get',
+              'retriever.query',
+              'memory.classify',
+              'memory.promoteDraft',
+              'registry.topology',
+            ]),
+          )
+          .max(16)
+          .optional(),
+        transport: z.enum(['stdio', 'http']).optional(),
+        http: z
+          .object({
+            port: z.number().int().min(1).max(65_535).optional(),
+            path: z.string().min(1).max(256).optional(),
+          })
+          .strict()
+          .optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict()
+
+export const IntelligenceConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    adapter: z
+      .object({
+        provider: z.enum(['openai', 'anthropic', 'ollama', 'openrouter', 'custom']),
+        model: z.string().min(1).max(128).optional(),
+        apiKeyEnv: z.string().min(0).max(128).optional(),
+        baseUrl: z.string().url().optional(),
+        options: z.record(z.string(), z.unknown()).optional(),
+      })
+      .strict()
+      .optional(),
+    chat: z
+      .object({
+        enabled: z.boolean().optional(),
+        sources: z.array(z.enum(['agent', 'human', 'federation'])).max(8).optional(),
+        handoffFirst: z.boolean().optional(),
+      })
+      .strict()
+      .optional(),
+    retriever: z
+      .object({
+        enabled: z.boolean().optional(),
+        mode: z.enum(['local', 'remote', 'bm25', 'agentskit-rag']).optional(),
+        embedModel: z.string().min(1).max(128).optional(),
+        chunkSize: z.number().int().min(128).max(16_384).optional(),
+        options: z.record(z.string(), z.unknown()).optional(),
+      })
+      .strict()
+      .optional(),
+    memory: z
+      .object({
+        enabled: z.boolean().optional(),
+        adapters: z
+          .array(z.enum(['playbook-memory', 'cursor-rules', 'session-export', 'bootstrap-delta']))
+          .max(8)
+          .optional(),
+        ingestDir: z.string().min(1).max(512).optional(),
+        classify: z.boolean().optional(),
+        promote: z
+          .object({
+            enabled: z.boolean().optional(),
+            targets: z.array(z.enum(['agent', 'human', 'agents-md'])).max(8).optional(),
+            requireApproval: z.boolean().optional(),
+          })
+          .strict()
+          .optional(),
+      })
+      .strict()
+      .optional(),
+    runtime: z.enum(['agentskit', 'custom']).optional(),
+    runtimeModule: z.string().min(1).max(512).optional(),
+  })
+  .strict()
+
+export const FederationConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    sources: z
+      .array(
+        z
+          .object({
+            id: z.string().min(1).max(64),
+            llmsTxt: z.string().min(1).max(512).optional(),
+            rawBaseUrl: z.string().url().optional(),
+            includeInRetriever: z.boolean().optional(),
+            includeInChat: z.boolean().optional(),
+          })
+          .strict(),
+      )
+      .max(16)
+      .optional(),
+  })
+  .strict()
+
+export const DocBridgeConfigV1Schema = z
+  .object({
+    schemaVersion: z.literal(CONFIG_SCHEMA_VERSION),
+    project: z
+      .object({
+        name: z.string().min(1).max(128).optional(),
+        root: z.string().min(1).max(512).optional(),
+      })
+      .strict()
+      .optional(),
+    corpus: z
+      .object({
+        agent: AgentCorpusConfigSchema,
+        human: z.union([HumanCorpusConfigSchema, z.array(HumanCorpusConfigSchema).max(8)]).optional(),
+      })
+      .strict(),
+    index: IndexConfigSchema.optional(),
+    routing: RoutingConfigSchema.optional(),
+    gates: GatesConfigSchema.optional(),
+    surfaces: SurfacesConfigSchema.optional(),
+    intelligence: IntelligenceConfigSchema.optional(),
+    federation: FederationConfigSchema.optional(),
+  })
+  .strict()
+
+export type DocBridgeConfigV1 = z.infer<typeof DocBridgeConfigV1Schema>
+export type AgentCorpusConfig = z.infer<typeof AgentCorpusConfigSchema>
+export type HumanCorpusConfig = z.infer<typeof HumanCorpusConfigSchema>

package/src/federation/llms.ts

@@ -0,0 +1,145 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import { slugFromPath } from '../lib/markdown.js'
+import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
+import {
+  retrieveDocBridgeChunks,
+  type DocBridgeRetrievedChunk,
+} from '../retriever/doc-bridge-retriever.js'
+
+export type FetchText = (url: string) => Promise<string>
+
+export type FederatedRetrieverOptions = {
+  readonly fetchText?: FetchText
+  readonly limit?: number
+}
+
+const tokenize = (value: string): string[] =>
+  value.toLowerCase().split(/[^a-z0-9]+/).filter((token) => token.length >= 2)
+
+const scoreText = (query: string, text: string): number => {
+  const hay = text.toLowerCase()
+  return tokenize(query).reduce((score, token) => score + (hay.includes(token) ? token.length : 0), 0)
+}
+
+const defaultFetchText: FetchText = async (url) => {
+  const signal = AbortSignal.timeout(5_000)
+  const res = await fetch(url, { signal })
+  if (!res.ok) throw new Error(`Failed to fetch ${url}: ${res.status}`)
+  return res.text()
+}
+
+const sourceText = async (
+  root: string,
+  source: string,
+  fetchText: FetchText,
+): Promise<string> => {
+  if (/^https?:\/\//.test(source)) return fetchText(source)
+  const path = resolve(root, source)
+  if (!existsSync(path)) throw new Error(`Federation source not found: ${source}`)
+  return readFileSync(path, 'utf8')
+}
+
+const sameOrigin = (base: string, target: string): boolean => {
+  if (!/^https?:\/\//.test(base) || !/^https?:\/\//.test(target)) return true
+  return new URL(base).origin === new URL(target).origin
+}
+
+export const parseLlmsTxtLinks = (raw: string): { title: string; url: string; description?: string }[] => {
+  const links = [...raw.matchAll(/\[([^\]]+)\]\(([^)]+)\)(?::\s*([^\n]+))?/g)].map((match) => ({
+    title: match[1] ?? match[2] ?? 'link',
+    url: match[2] ?? '',
+    ...(match[3]?.trim() ? { description: match[3].trim() } : {}),
+  })).filter((link) => link.url)
+
+  for (const match of raw.matchAll(/(?:^|\s)(?:Raw|llms\.txt|Full bundle|ZIP bundle)?:?\s*(https?:\/\/\S+)/gi)) {
+    const url = match[1]?.replace(/[),.;]+$/, '')
+    if (url && !links.some((link) => link.url === url)) links.push({ title: slugFromPath(url), url })
+  }
+  return links
+}
+
+export const chunksFromMarkdown = (
+  property: string,
+  raw: string,
+  sourceUrl: string,
+): DocBridgeRetrievedChunk[] => {
+  const searchable = raw.includes('\n==== ') ? raw : raw.replace(/^---\n[\s\S]*?\n---\n?/, '')
+  const sections = searchable.includes('\n==== ')
+    ? searchable.split(/\n====\s+/).filter((section) => section.trim())
+    : searchable.split(/\n(?=##?\s+)/)
+  return sections.map((section, index) => {
+    const title =
+      /^title:\s*(.+)$/m.exec(section)?.[1]?.trim() ??
+      /^https?:\/\/\S+\/([^/\s]+)$/m.exec(section)?.[1]?.trim() ??
+      /^#+\s+(.+)$/m.exec(section)?.[1]?.trim() ??
+      slugFromPath(sourceUrl)
+    const id = slugFromPath(title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')) || `${index}`
+    return {
+      chunkKey: `${property}:federated:${id}`,
+      property,
+      type: 'federated',
+      id,
+      path: sourceUrl,
+      title,
+      summary: section.trim().slice(0, 500),
+      score: 0,
+    }
+  })
+}
+
+export const loadFederatedChunks = async (
+  root: string,
+  config: DocBridgeConfigV1,
+  options: FederatedRetrieverOptions = {},
+): Promise<DocBridgeRetrievedChunk[]> => {
+  const fetchText = options.fetchText ?? defaultFetchText
+  const chunks: DocBridgeRetrievedChunk[] = []
+  for (const source of config.federation?.sources ?? []) {
+    if (source.includeInRetriever === false || !source.llmsTxt) continue
+    const llms = await sourceText(root, source.llmsTxt, fetchText)
+    chunks.push(...chunksFromMarkdown(source.id, llms, source.llmsTxt))
+    const links = parseLlmsTxtLinks(llms)
+    for (const link of links) {
+      const url = !/^https?:\/\//.test(link.url) && source.rawBaseUrl
+        ? `${source.rawBaseUrl.replace(/\/$/, '')}/${link.url.replace(/^\//, '')}`
+        : link.url
+      if (!/\.(md|txt)(?:$|\?)/.test(url)) continue
+      if (!sameOrigin(source.llmsTxt, url)) continue
+      try {
+        const raw = await sourceText(root, url, fetchText)
+        chunks.push(...chunksFromMarkdown(source.id, raw, url))
+      } catch {
+        // ponytail: federation is best-effort; surface-level health belongs in a future diagnostic command.
+      }
+    }
+  }
+  return chunks
+}
+
+export const retrieveHybridChunks = async (
+  root: string,
+  config: DocBridgeConfigV1,
+  index: DocBridgeIndexV1,
+  query: string,
+  options: FederatedRetrieverOptions = {},
+): Promise<DocBridgeRetrievedChunk[]> => {
+  const limit = options.limit ?? 8
+  const local = retrieveDocBridgeChunks(index, query, {
+    property: config.project?.name ?? index.project?.name ?? 'local',
+    limit,
+  })
+  const federated = (await loadFederatedChunks(root, config, options)).map((chunk) => ({
+    ...chunk,
+    score: scoreText(query, `${chunk.title ?? ''} ${chunk.summary ?? ''} ${chunk.path}`),
+  })).filter((chunk) => chunk.score > 0)
+
+  const byKey = new Map<string, DocBridgeRetrievedChunk>()
+  for (const chunk of [...local, ...federated]) {
+    const existing = byKey.get(chunk.chunkKey)
+    if (!existing || chunk.score > existing.score) byKey.set(chunk.chunkKey, chunk)
+  }
+  return [...byKey.values()].sort((a, b) => b.score - a.score).slice(0, limit)
+}