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

package/src/query/query.ts

@@ -0,0 +1,142 @@
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import {
+  normalizeAgentHandoff,
+  type AgentHandoffV1,
+  type AgentSearchV1,
+} from '../schemas/agent-handoff.js'
+import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
+import { searchIndex } from './search.js'
+
+export type QueryKind = 'package' | 'ownership' | 'intent' | 'change' | 'search'
+
+export type QueryRequest = {
+  readonly kind: QueryKind
+  readonly id?: string
+  readonly term?: string
+  readonly agent?: boolean
+}
+
+export type QueryResult =
+  | { readonly type: 'package' | 'ownership' | 'intent' | 'change' | 'search'; readonly data: unknown }
+  | AgentHandoffV1
+  | AgentSearchV1
+
+const handoffForPackage = (
+  index: DocBridgeIndexV1,
+  id: string,
+  config: DocBridgeConfigV1,
+): AgentHandoffV1 => {
+  const fromIndex = index.handoffs?.[id]
+  if (fromIndex) return normalizeAgentHandoff(fromIndex)
+
+  const owner = index.lookup?.ownership?.[id]
+  if (!owner) throw new Error(`Unknown package/ownership id "${id}". Try: ak-docs list packages`)
+
+  return normalizeAgentHandoff({
+    type: 'agent-handoff',
+    source: config.index?.outFile ?? '.doc-bridge/index.json',
+    target: {
+      type: 'package',
+      id,
+      path: owner.path,
+      ...(owner.group ? { group: owner.group } : {}),
+      ...(owner.layer ? { layer: owner.layer } : {}),
+    },
+    startHere: owner.agentDoc ?? config.corpus.agent.index ?? '',
+    readBeforeEditing: [owner.agentDoc, 'AGENTS.md'].filter(Boolean),
+    editRoots: [owner.path],
+    checks: [...owner.checks],
+    ...(owner.humanDoc ? { humanDoc: owner.humanDoc } : {}),
+    notes: owner.purpose ? [owner.purpose] : [],
+  })
+}
+
+export const runQuery = (
+  index: DocBridgeIndexV1,
+  config: DocBridgeConfigV1,
+  req: QueryRequest,
+): QueryResult => {
+  if (req.kind === 'search') {
+    const term = req.term ?? req.id ?? ''
+    const matches = searchIndex(index, term)
+    if (req.agent) {
+      const payload: AgentSearchV1 = {
+        type: 'agent-search',
+        schemaVersion: 1,
+        source: config.index?.outFile ?? '.doc-bridge/index.json',
+        term,
+        count: matches.length,
+        bestMatch: matches[0]
+          ? {
+              type: matches[0].type,
+              id: matches[0].id,
+              path: matches[0].path,
+              ...(matches[0].summary ? { summary: matches[0].summary } : {}),
+              score: matches[0].score,
+            }
+          : null,
+        matches: matches.slice(0, 8).map((m) => ({
+          type: m.type,
+          id: m.id,
+          path: m.path,
+          ...(m.summary ? { summary: m.summary } : {}),
+          score: m.score,
+        })),
+        nextCommands: [...new Set(matches.slice(0, 5).map((m) =>
+          m.type === 'ownership' || index.lookup?.ownership?.[m.id]
+            ? `ak-docs query ownership ${m.id} --agent`
+            : 'ak-docs list knowledge --text',
+        ))],
+      }
+      return payload
+    }
+    return { type: 'search', data: { term, count: matches.length, matches } }
+  }
+
+  const id = req.id
+  if (!id) throw new Error(`Missing id for query kind "${req.kind}"`)
+
+  if (req.kind === 'package' || req.kind === 'ownership') {
+    if (req.agent) return handoffForPackage(index, id, config)
+    const owner = index.lookup?.ownership?.[id]
+    return { type: req.kind, data: owner ?? index.handoffs?.[id] ?? null }
+  }
+
+  if (req.kind === 'intent') {
+    const intent = index.lookup?.intents?.[id]
+    if (!intent) throw new Error(`Unknown intent "${id}"`)
+    if (req.agent) {
+      return normalizeAgentHandoff({
+        type: 'agent-handoff',
+        source: config.index?.outFile ?? '.doc-bridge/index.json',
+        target: { type: 'intent', id },
+        startHere: intent.paths[0] ?? '',
+        readBeforeEditing: [...intent.paths],
+        editRoots: [],
+        checks: [],
+        notes: [intent.title],
+      })
+    }
+    return { type: 'intent', data: intent }
+  }
+
+  if (req.kind === 'change') {
+    const change = index.lookup?.changes?.[id]
+    if (!change) throw new Error(`Unknown change route "${id}"`)
+    if (req.agent) {
+      return normalizeAgentHandoff({
+        type: 'agent-handoff',
+        source: config.index?.outFile ?? '.doc-bridge/index.json',
+        target: { type: 'change', id },
+        startHere: change.startHere,
+        readBeforeEditing: ['AGENTS.md', config.corpus.agent.index ?? ''].filter(Boolean),
+        editRoots: [change.startHere],
+        checks: [],
+        notes: [change.title],
+      })
+    }
+    return { type: 'change', data: change }
+  }
+
+  throw new Error(`Unsupported query kind: ${req.kind as string}`)
+}

package/src/query/search.ts

@@ -0,0 +1,58 @@
+import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
+
+export type SearchMatch = {
+  readonly type: string
+  readonly id: string
+  readonly path: string
+  readonly summary?: string
+  readonly score: number
+}
+
+const tokenize = (value: string): string[] =>
+  value
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((t) => t.length >= 2)
+
+export const searchIndex = (index: DocBridgeIndexV1, term: string, limit = 20): SearchMatch[] => {
+  const tokens = tokenize(term)
+  if (!tokens.length) return []
+
+  const matches: 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
+    }
+    if (score > 0) {
+      matches.push({
+        type: 'knowledge',
+        id: entry.id,
+        path: entry.path,
+        ...(entry.description ? { summary: entry.description } : {}),
+        score,
+      })
+    }
+  }
+
+  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
+    }
+    if (score > 0) {
+      matches.push({
+        type: 'ownership',
+        id,
+        path: owner.agentDoc ?? owner.path,
+        ...(owner.purpose ? { summary: owner.purpose } : {}),
+        score,
+      })
+    }
+  }
+
+  return matches.sort((a, b) => b.score - a.score).slice(0, limit)
+}

package/src/retriever/doc-bridge-retriever.ts

@@ -0,0 +1,62 @@
+import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
+import { searchIndex } from '../query/search.js'
+
+export type DocBridgeRetrieverOptions = {
+  readonly property?: string
+  readonly limit?: number
+}
+
+export type DocBridgeRetrievedChunk = {
+  readonly chunkKey: string
+  readonly property: string
+  readonly type: string
+  readonly id: string
+  readonly path: string
+  readonly title?: string
+  readonly summary?: string
+  readonly score: number
+}
+
+export type DocBridgeRetriever = {
+  readonly retrieve: (
+    query: string,
+    options?: Pick<DocBridgeRetrieverOptions, 'limit'>,
+  ) => DocBridgeRetrievedChunk[]
+}
+
+const chunkKey = (property: string, type: string, id: string): string =>
+  `${property}:${type}:${id}`
+
+export const retrieveDocBridgeChunks = (
+  index: DocBridgeIndexV1,
+  query: string,
+  options: DocBridgeRetrieverOptions = {},
+): DocBridgeRetrievedChunk[] => {
+  const property = options.property ?? index.project?.name ?? 'local'
+  const limit = options.limit ?? 8
+
+  return searchIndex(index, query, limit).map((match) => {
+    const knowledge = index.knowledge.find((entry) => entry.id === match.id && entry.path === match.path)
+    const owner = index.lookup?.ownership?.[match.id]
+    const type = match.type === 'ownership' ? 'ownership' : (knowledge?.type ?? match.type)
+    const summary = match.summary ?? owner?.purpose
+    return {
+      chunkKey: chunkKey(property, type, match.id),
+      property,
+      type,
+      id: match.id,
+      path: match.path,
+      ...(knowledge?.title ? { title: knowledge.title } : {}),
+      ...(summary ? { summary } : {}),
+      score: match.score,
+    }
+  })
+}
+
+export const createDocBridgeRetriever = (
+  index: DocBridgeIndexV1,
+  options: DocBridgeRetrieverOptions = {},
+): DocBridgeRetriever => ({
+  retrieve: (query, req = {}) =>
+    retrieveDocBridgeChunks(index, query, { ...options, ...req }),
+})

package/src/schemas/agent-handoff.ts

@@ -0,0 +1,82 @@
+import { z } from 'zod'
+
+export const HANDOFF_SCHEMA_VERSION = 1 as const
+
+export const HandoffTargetTypeSchema = z.enum([
+  'package',
+  'module',
+  'app',
+  'screen',
+  'flow',
+  'component',
+  'intent',
+  'change',
+  'search',
+])
+
+export type HandoffTargetType = z.infer<typeof HandoffTargetTypeSchema>
+
+export const HandoffTargetSchema = z
+  .object({
+    type: HandoffTargetTypeSchema,
+    id: z.string().min(1).max(256),
+    path: z.string().min(1).max(512).optional(),
+    group: z.string().min(1).max(128).optional(),
+    layer: z.string().min(1).max(32).optional(),
+  })
+  .strict()
+
+export type HandoffTarget = z.infer<typeof HandoffTargetSchema>
+
+/** v1 — canonical AgentHandoff. Legacy payloads may omit schemaVersion. */
+export const AgentHandoffV1Schema = z
+  .object({
+    type: z.literal('agent-handoff'),
+    schemaVersion: z.literal(HANDOFF_SCHEMA_VERSION).default(HANDOFF_SCHEMA_VERSION),
+    source: z.string().min(1).max(512),
+    target: HandoffTargetSchema,
+    startHere: z.string().min(1).max(512),
+    readBeforeEditing: z.array(z.string().min(1).max(512)).max(64),
+    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(),
+    playbookPatterns: z.array(z.string().url()).max(16).optional(),
+    notes: z.array(z.string().min(1).max(1024)).max(16),
+  })
+  .strict()
+
+export type AgentHandoffV1 = z.infer<typeof AgentHandoffV1Schema>
+
+/** Accept legacy handoffs without schemaVersion. */
+export const AgentHandoffLegacySchema = AgentHandoffV1Schema.omit({ schemaVersion: true }).extend({
+  schemaVersion: z.literal(HANDOFF_SCHEMA_VERSION).optional(),
+})
+
+export const AgentSearchMatchSchema = z
+  .object({
+    type: z.string().min(1).max(64),
+    id: z.string().min(1).max(256),
+    path: z.string().min(1).max(512),
+    summary: z.string().max(2048).optional(),
+    score: z.number().optional(),
+    refs: z.number().int().nonnegative().optional(),
+  })
+  .strict()
+
+export const AgentSearchV1Schema = z
+  .object({
+    type: z.literal('agent-search'),
+    schemaVersion: z.literal(HANDOFF_SCHEMA_VERSION).default(HANDOFF_SCHEMA_VERSION),
+    source: z.string().min(1).max(512),
+    term: z.string().min(1).max(512),
+    count: z.number().int().nonnegative(),
+    bestMatch: AgentSearchMatchSchema.nullable(),
+    matches: z.array(AgentSearchMatchSchema).max(32),
+    nextCommands: z.array(z.string().min(1).max(512)).max(16),
+  })
+  .strict()
+
+export type AgentSearchV1 = z.infer<typeof AgentSearchV1Schema>
+
+export const normalizeAgentHandoff = (input: unknown): AgentHandoffV1 =>
+  AgentHandoffV1Schema.parse(AgentHandoffLegacySchema.parse(input))

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

@@ -0,0 +1,106 @@
+import { z } from 'zod'
+
+import { AgentHandoffLegacySchema } from './agent-handoff.js'
+
+export const INDEX_SCHEMA_VERSION = 1 as const
+
+export const ContentHashAlgoSchema = z.literal('sha256-normalized-v1')
+
+export const EcosystemPropertySchema = z
+  .object({
+    id: z.string().min(1).max(64),
+    name: z.string().min(1).max(128),
+    url: z.string().url().optional(),
+    llms: z.string().url().optional(),
+  })
+  .strict()
+
+export const KnowledgeEntrySchema = z
+  .object({
+    id: z.string().min(1).max(256),
+    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(),
+    links: z.array(z.string().min(1).max(512)).max(64).optional(),
+    tags: z.array(z.string().min(1).max(64)).max(32).optional(),
+  })
+  .strict()
+
+export const CapabilityRefSchema = z
+  .object({
+    id: z.string().min(1).max(256),
+    kind: z.string().min(1).max(64),
+    description: z.string().max(512).optional(),
+  })
+  .strict()
+
+export const OwnershipRecordSchema = z
+  .object({
+    id: z.string().min(1).max(256),
+    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),
+    agentDoc: z.string().min(1).max(512).optional(),
+    humanDoc: z.string().min(1).max(512).optional(),
+    readme: z.string().min(1).max(512).optional(),
+  })
+  .strict()
+
+export const IndexLookupSchema = z
+  .object({
+    packages: z.array(z.string().min(1).max(256)).max(2_000),
+    ownership: z.record(z.string().min(1).max(256), OwnershipRecordSchema).optional(),
+    intents: z
+      .record(
+        z.string().min(1).max(128),
+        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(),
+      )
+      .optional(),
+    changes: z
+      .record(
+        z.string().min(1).max(128),
+        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(),
+      )
+      .optional(),
+  })
+  .strict()
+
+export const DocBridgeIndexV1Schema = z
+  .object({
+    schemaVersion: z.literal(INDEX_SCHEMA_VERSION),
+    contentHash: z.string().regex(/^[a-f0-9]{64}$/),
+    contentHashAlgo: ContentHashAlgoSchema,
+    generatedAt: z.string().datetime().optional(),
+    project: z
+      .object({
+        name: z.string().min(1).max(128),
+        root: z.string().min(1).max(512).optional(),
+      })
+      .strict()
+      .optional(),
+    properties: z.array(EcosystemPropertySchema).max(16).optional(),
+    knowledge: z.array(KnowledgeEntrySchema).max(10_000),
+    capabilities: z.array(CapabilityRefSchema).max(5_000).optional(),
+    handoffs: z.record(z.string().min(1).max(256), AgentHandoffLegacySchema).optional(),
+    lookup: IndexLookupSchema.optional(),
+  })
+  .strict()
+
+export type DocBridgeIndexV1 = z.infer<typeof DocBridgeIndexV1Schema>
+export type KnowledgeEntry = z.infer<typeof KnowledgeEntrySchema>

package/src/schemas/json-schemas.ts

@@ -0,0 +1,156 @@
+type JsonSchema = {
+  readonly [key: string]: unknown
+}
+
+const stringArray = (maxItems: number): JsonSchema => ({
+  type: 'array',
+  items: { type: 'string', minLength: 1 },
+  maxItems,
+})
+
+export const AgentHandoffV1JsonSchema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $id: 'https://agentskit.io/schemas/doc-bridge/agent-handoff-v1.schema.json',
+  title: 'AgentHandoff v1',
+  type: 'object',
+  additionalProperties: false,
+  required: [
+    'type',
+    'schemaVersion',
+    'source',
+    'target',
+    'startHere',
+    'readBeforeEditing',
+    'editRoots',
+    'checks',
+    'notes',
+  ],
+  properties: {
+    type: { const: 'agent-handoff' },
+    schemaVersion: { const: 1 },
+    source: { type: 'string', minLength: 1, maxLength: 512 },
+    target: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['type', 'id'],
+      properties: {
+        type: {
+          enum: ['package', 'module', 'app', 'screen', 'flow', 'component', 'intent', 'change', 'search'],
+        },
+        id: { type: 'string', minLength: 1, maxLength: 256 },
+        path: { type: 'string', minLength: 1, maxLength: 512 },
+        group: { type: 'string', minLength: 1, maxLength: 128 },
+        layer: { type: 'string', minLength: 1, maxLength: 32 },
+      },
+    },
+    startHere: { type: 'string', minLength: 1, maxLength: 512 },
+    readBeforeEditing: stringArray(64),
+    editRoots: stringArray(32),
+    checks: stringArray(32),
+    humanDoc: { anyOf: [{ type: 'string', minLength: 1, maxLength: 512 }, { type: 'null' }] },
+    playbookPatterns: { type: 'array', items: { type: 'string', format: 'uri' }, maxItems: 16 },
+    notes: stringArray(16),
+  },
+} as const satisfies JsonSchema
+
+export const MemoryCandidateV1JsonSchema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $id: 'https://agentskit.io/schemas/doc-bridge/memory-candidate-v1.schema.json',
+  title: 'MemoryCandidate v1',
+  type: 'object',
+  additionalProperties: false,
+  required: ['schemaVersion', 'id', 'source', 'fact', 'suggestedType', 'confidence', 'references'],
+  properties: {
+    schemaVersion: { const: 1 },
+    id: { type: 'string', minLength: 1, maxLength: 256 },
+    source: { enum: ['cursor', 'claude', 'codex', 'copilot', 'agent-memory', 'manual'] },
+    rawPath: { type: 'string', minLength: 1, maxLength: 512 },
+    fact: { type: 'string', minLength: 1, maxLength: 8000 },
+    why: { type: 'string', maxLength: 4000 },
+    howToApply: { type: 'string', maxLength: 4000 },
+    suggestedType: { enum: ['user', 'feedback', 'project', 'reference', 'unknown'] },
+    confidence: { type: 'number', minimum: 0, maximum: 1 },
+    references: stringArray(64),
+  },
+} as const satisfies JsonSchema
+
+export const DocBridgeIndexV1JsonSchema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  $id: 'https://agentskit.io/schemas/doc-bridge/doc-bridge-index-v1.schema.json',
+  title: 'DocBridgeIndex v1',
+  type: 'object',
+  additionalProperties: false,
+  required: ['schemaVersion', 'contentHash', 'contentHashAlgo', 'knowledge'],
+  properties: {
+    schemaVersion: { const: 1 },
+    contentHash: { type: 'string', pattern: '^[a-f0-9]{64}$' },
+    contentHashAlgo: { const: 'sha256-normalized-v1' },
+    generatedAt: { type: 'string', format: 'date-time' },
+    project: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        name: { type: 'string', minLength: 1, maxLength: 128 },
+        root: { type: 'string', minLength: 1, maxLength: 512 },
+      },
+    },
+    properties: {
+      type: 'array',
+      maxItems: 16,
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['id', 'name'],
+        properties: {
+          id: { type: 'string', minLength: 1, maxLength: 64 },
+          name: { type: 'string', minLength: 1, maxLength: 128 },
+          url: { type: 'string', format: 'uri' },
+          llms: { type: 'string', format: 'uri' },
+        },
+      },
+    },
+    knowledge: {
+      type: 'array',
+      maxItems: 10000,
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['id', 'type', 'title', 'path'],
+        properties: {
+          id: { type: 'string', minLength: 1, maxLength: 256 },
+          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 },
+          links: stringArray(64),
+          tags: stringArray(32),
+        },
+      },
+    },
+    capabilities: {
+      type: 'array',
+      maxItems: 5000,
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['id', 'kind'],
+        properties: {
+          id: { type: 'string', minLength: 1, maxLength: 256 },
+          kind: { type: 'string', minLength: 1, maxLength: 64 },
+          description: { type: 'string', maxLength: 512 },
+        },
+      },
+    },
+    handoffs: {
+      type: 'object',
+      additionalProperties: { type: 'object' },
+    },
+    lookup: { type: 'object' },
+  },
+} as const satisfies JsonSchema
+
+export const DocBridgeJsonSchemas = {
+  agentHandoffV1: AgentHandoffV1JsonSchema,
+  docBridgeIndexV1: DocBridgeIndexV1JsonSchema,
+  memoryCandidateV1: MemoryCandidateV1JsonSchema,
+} as const

package/src/schemas/memory-candidate.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod'
+
+export const MEMORY_CANDIDATE_SCHEMA_VERSION = 1 as const
+
+export const MemorySourceSchema = z.enum([
+  'cursor',
+  'claude',
+  'codex',
+  'copilot',
+  'agent-memory',
+  'manual',
+])
+
+export const MemorySuggestedTypeSchema = z.enum([
+  'user',
+  'feedback',
+  'project',
+  'reference',
+  'unknown',
+])
+
+export const MemoryCandidateV1Schema = z
+  .object({
+    schemaVersion: z.literal(MEMORY_CANDIDATE_SCHEMA_VERSION),
+    id: z.string().min(1).max(256),
+    source: MemorySourceSchema,
+    rawPath: z.string().min(1).max(512).optional(),
+    fact: z.string().min(1).max(8_000),
+    why: z.string().max(4_000).optional(),
+    howToApply: z.string().max(4_000).optional(),
+    suggestedType: MemorySuggestedTypeSchema,
+    confidence: z.number().min(0).max(1),
+    references: z.array(z.string().min(1).max(512)).max(64),
+  })
+  .strict()
+
+export type MemoryCandidateV1 = z.infer<typeof MemoryCandidateV1Schema>