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

package/src/gates/run-gates.ts

@@ -0,0 +1,274 @@
+import { readFileSync } from 'node:fs'
+
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import { buildDocBridgeIndex } from '../index-builder/build-index.js'
+import { scanAgentCorpus } from '../index-builder/scan-corpus.js'
+import { scanHumanDocRecords } from '../index-builder/human-adapters/index.js'
+import { IndexNotFoundError, loadDocBridgeIndex } from '../query/load-index.js'
+
+export type GateId = 'index-freshness' | 'human-guide-links' | 'okf-type' | 'docs-style'
+
+const SUPPORTED_GATES = ['index-freshness', 'human-guide-links', 'okf-type', 'docs-style'] as const
+
+export type GateResult = {
+  readonly id: GateId
+  readonly ok: boolean
+  readonly message: string
+  readonly expected?: string
+  readonly actual?: string
+}
+
+export type GateRunResult = {
+  readonly ok: boolean
+  readonly results: GateResult[]
+}
+
+export const runGate = (
+  root: string,
+  config: DocBridgeConfigV1,
+  id: GateId,
+): GateResult => {
+  if (id === 'human-guide-links') return runHumanGuideLinksGate(root, config)
+  if (id === 'okf-type') return runOkfTypeGate(root, config)
+  if (id === 'docs-style') return runDocsStyleGate(root, config)
+  if (id !== 'index-freshness') throw new Error(`Unsupported gate "${id}"`)
+
+  let current: string
+  try {
+    current = loadDocBridgeIndex(root, config).contentHash
+  } catch (error) {
+    if (error instanceof IndexNotFoundError) {
+      return { id, ok: false, message: error.message }
+    }
+    throw error
+  }
+
+  const next = buildDocBridgeIndex({ root, config, write: false }).index.contentHash
+  if (current !== next) {
+    return {
+      id,
+      ok: false,
+      message: 'Index is stale. Run: ak-docs index',
+      expected: next,
+      actual: current,
+    }
+  }
+
+  return { id, ok: true, message: 'Index is fresh', expected: next, actual: current }
+}
+
+const runHumanGuideLinksGate = (root: string, config: DocBridgeConfigV1): GateResult => {
+  const urls = new Set(scanHumanDocRecords(root, config).map((doc) => doc.url))
+  const index = buildDocBridgeIndex({ root, config, write: false }).index
+  const localHumanDocs = Object.values(index.handoffs ?? {})
+    .map((handoff) => handoff.humanDoc)
+    .filter((url): url is string => typeof url === 'string' && url.length > 0)
+    .filter((url) => !/^https?:\/\//.test(url))
+  const missing = localHumanDocs.filter((url, i, all) => !urls.has(url) && all.indexOf(url) === i)
+
+  if (missing.length) {
+    return {
+      id: 'human-guide-links',
+      ok: false,
+      message: `Broken humanDoc links: ${missing.join(', ')}`,
+      expected: 'all local humanDoc links resolve',
+      actual: `${missing.length} broken`,
+    }
+  }
+
+  return {
+    id: 'human-guide-links',
+    ok: true,
+    message: `Resolved ${localHumanDocs.length} humanDoc link(s)`,
+  }
+}
+
+const frontmatterType = (markdown: string): string | undefined => {
+  const match = /^---\n([\s\S]*?)\n---/.exec(markdown)
+  return match?.[1]?.match(/^type:\s*['"]?([^'"\n#]+)['"]?/m)?.[1]?.trim()
+}
+
+const frontmatterField = (markdown: string, field: string): string | undefined => {
+  const match = /^---\n([\s\S]*?)\n---/.exec(markdown)
+  return match?.[1]?.match(new RegExp(`^${field}:\\s*['"]?([^'\"\\n#]+)['"]?`, 'm'))?.[1]?.trim()
+}
+
+const runOkfTypeGate = (root: string, config: DocBridgeConfigV1): GateResult => {
+  const required = config.corpus.agent.okf?.requireType ?? config.gates?.preset === 'strict'
+  if (!required) return { id: 'okf-type', ok: true, message: 'OKF type frontmatter not required' }
+
+  const allowed = config.corpus.agent.okf?.allowedTypes
+  const bad = scanAgentCorpus(root, config)
+    .filter((doc) => doc.path !== config.corpus.agent.index)
+    .map((doc) => ({ path: doc.path, type: frontmatterType(readFileSync(doc.absPath, 'utf8')) }))
+    .filter((doc) => !doc.type || (allowed && !allowed.includes(doc.type)))
+
+  if (bad.length) {
+    return {
+      id: 'okf-type',
+      ok: false,
+      message: `Missing or invalid OKF type frontmatter: ${bad.map((doc) => doc.path).join(', ')}`,
+      expected: allowed?.length ? `type: ${allowed.join(' | ')}` : 'type frontmatter',
+      actual: `${bad.length} invalid`,
+    }
+  }
+
+  return { id: 'okf-type', ok: true, message: 'All agent docs have OKF type frontmatter' }
+}
+
+type DocsStyleRule =
+  | 'title'
+  | 'purpose'
+  | 'audience'
+  | 'task-orientation'
+  | 'examples'
+  | 'owner-source'
+  | 'no-stale-wording'
+
+type DocsStyleProfile =
+  | 'google-dev-docs'
+  | 'playbook-okf'
+  | 'playbook-okf-soft'
+  | 'title-only'
+  | 'custom'
+
+const DOCS_STYLE_RULES: Record<Exclude<DocsStyleProfile, 'custom'>, DocsStyleRule[]> = {
+  'google-dev-docs': [
+    'title',
+    'purpose',
+    'audience',
+    'task-orientation',
+    'examples',
+    'no-stale-wording',
+  ],
+  /** Full playbook OKF style (strict). */
+  'playbook-okf': ['title', 'purpose', 'owner-source', 'no-stale-wording'],
+  /** Soft profile for large existing OKF corpora (title + no stale placeholders). */
+  'playbook-okf-soft': ['title', 'no-stale-wording'],
+  'title-only': ['title'],
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const docsStyleOptions = (
+  config: DocBridgeConfigV1,
+): { profile: DocsStyleProfile; required: DocsStyleRule[] } => {
+  const raw = config.gates?.options?.['docs-style']
+  if (!isRecord(raw)) {
+    if (config.gates?.preset === 'playbook') {
+      return { profile: 'playbook-okf-soft', required: DOCS_STYLE_RULES['playbook-okf-soft'] }
+    }
+    return { profile: 'playbook-okf', required: DOCS_STYLE_RULES['playbook-okf'] }
+  }
+
+  const profile =
+    raw.profile === 'google-dev-docs' ||
+    raw.profile === 'playbook-okf' ||
+    raw.profile === 'playbook-okf-soft' ||
+    raw.profile === 'title-only' ||
+    raw.profile === 'custom'
+      ? raw.profile
+      : 'playbook-okf'
+  const customRequired = Array.isArray(raw.required)
+    ? raw.required.filter((rule): rule is DocsStyleRule =>
+        [
+          'title',
+          'purpose',
+          'audience',
+          'task-orientation',
+          'examples',
+          'owner-source',
+          'no-stale-wording',
+        ].includes(String(rule)),
+      )
+    : []
+
+  return {
+    profile,
+    required: profile === 'custom' ? customRequired : DOCS_STYLE_RULES[profile],
+  }
+}
+
+const missingStyleRules = (markdown: string, rules: readonly DocsStyleRule[]): DocsStyleRule[] => {
+  const checks: Record<DocsStyleRule, boolean> = {
+    title: /^#\s+\S+/m.test(markdown),
+    purpose: Boolean(frontmatterField(markdown, 'purpose') || /^##\s+(Purpose|Goal)\b/im.test(markdown)),
+    audience: Boolean(frontmatterField(markdown, 'audience') || /^##\s+Audience\b/im.test(markdown)),
+    'task-orientation': /^##\s+(How to|Usage|Workflow|Tasks?)\b/im.test(markdown),
+    examples: /^##\s+Examples?\b/im.test(markdown) || /```[\s\S]*?```/.test(markdown),
+    'owner-source': Boolean(
+      frontmatterField(markdown, 'owner') ||
+        frontmatterField(markdown, 'source') ||
+        /^(Owner|Source):\s+\S+/im.test(markdown),
+    ),
+    'no-stale-wording': !/\b(TODO|TBD|coming soon|eventually|placeholder)\b/i.test(markdown),
+  }
+
+  return rules.filter((rule) => !checks[rule])
+}
+
+const runDocsStyleGate = (root: string, config: DocBridgeConfigV1): GateResult => {
+  const { profile, required } = docsStyleOptions(config)
+  if (!required.length) {
+    return { id: 'docs-style', ok: true, message: 'No docs-style rules configured' }
+  }
+
+  const bad = scanAgentCorpus(root, config)
+    .filter((doc) => doc.path !== config.corpus.agent.index)
+    .map((doc) => ({
+      path: doc.path,
+      missing: missingStyleRules(readFileSync(doc.absPath, 'utf8'), required),
+    }))
+    .filter((doc) => doc.missing.length > 0)
+
+  if (bad.length) {
+    return {
+      id: 'docs-style',
+      ok: false,
+      message: `Docs style issues: ${bad
+        .map((doc) => `${doc.path} (${doc.missing.join(', ')})`)
+        .join('; ')}`,
+      expected: `${profile}: ${required.join(', ')}`,
+      actual: `${bad.length} file(s) with style issues`,
+    }
+  }
+
+  return {
+    id: 'docs-style',
+    ok: true,
+    message: `All agent docs pass ${profile} docs-style rules`,
+  }
+}
+
+export const runGates = (
+  root: string,
+  config: DocBridgeConfigV1,
+  ids?: readonly GateId[],
+): GateRunResult => {
+  const results = (ids ?? resolveGateIds(config)).map((id) => runGate(root, config, id))
+  return { ok: results.every((result) => result.ok), results }
+}
+
+export const resolveGateIds = (config: DocBridgeConfigV1): GateId[] => {
+  const preset = config.gates?.preset ?? 'minimal'
+  const ids = new Set<GateId>(
+    preset === 'minimal'
+      ? ['index-freshness']
+      : preset === 'strict'
+        ? ['index-freshness', 'human-guide-links', 'okf-type', 'docs-style']
+        : preset === 'playbook'
+          ? // okf-type only — docs-style soft is opt-in via include (large corpora vary)
+            ['index-freshness', 'okf-type']
+          : ['index-freshness', 'human-guide-links'],
+  )
+
+  for (const id of config.gates?.include ?? []) {
+    if (SUPPORTED_GATES.includes(id as GateId)) ids.add(id as GateId)
+  }
+  for (const id of config.gates?.exclude ?? []) {
+    if (SUPPORTED_GATES.includes(id as GateId)) ids.delete(id as GateId)
+  }
+
+  return [...ids]
+}

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

@@ -0,0 +1,217 @@
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import { defaultChecksForTarget } from '../lib/package-manager.js'
+import type { AgentHandoffV1 } from '../schemas/agent-handoff.js'
+import {
+  guessAgentDocForPackage,
+  ownershipFromCorpus,
+  ownershipFromFrontmatter,
+  type CorpusDoc,
+} from './scan-corpus.js'
+import type { DiscoveredPackage } from './plugins/pnpm-monorepo.js'
+import type { HumanDocMap } from './plugins/human-markdown.js'
+
+export type IndexLookup = {
+  packages: string[]
+  ownership: Record<string, OwnershipRecord>
+  intents: Record<string, IntentRecord>
+  changes: Record<string, ChangeRecord>
+}
+
+export type OwnershipRecord = {
+  id: string
+  path: string
+  group?: string
+  layer?: string
+  purpose?: string
+  checks: string[]
+  agentDoc?: string
+  humanDoc?: string
+  readme?: string
+}
+
+export type IntentRecord = {
+  id: string
+  title: string
+  paths: string[]
+}
+
+export type ChangeRecord = {
+  id: string
+  title: string
+  startHere: string
+  relatedPackages?: string[]
+}
+
+/**
+ * Merge package identity from:
+ * 1. routing.options.ownership (explicit)
+ * 2. pnpm / workspace discovery
+ * 3. agent-doc frontmatter (package + editRoot)
+ * 4. corpus path heuristics (packages/<id>.md, pillars patterns, etc.)
+ */
+export const collectPackages = (
+  config: DocBridgeConfigV1,
+  discovered: readonly DiscoveredPackage[],
+  corpus: readonly CorpusDoc[],
+): DiscoveredPackage[] => {
+  const byId = new Map<string, DiscoveredPackage>()
+
+  for (const [id, entry] of Object.entries(config.routing?.options?.ownership ?? {})) {
+    byId.set(id, { id, path: entry.path })
+  }
+
+  for (const pkg of discovered) {
+    const existing = byId.get(pkg.id)
+    if (!existing) {
+      byId.set(pkg.id, pkg)
+      continue
+    }
+    byId.set(pkg.id, {
+      id: pkg.id,
+      path: existing.path || pkg.path,
+      ...(pkg.name ? { name: pkg.name } : existing.name ? { name: existing.name } : {}),
+    })
+  }
+
+  const seeds = [
+    ...ownershipFromFrontmatter(corpus),
+    ...(config.routing?.options?.ownershipFromCorpus === false
+      ? []
+      : ownershipFromCorpus(corpus)),
+  ]
+
+  for (const seed of seeds) {
+    const existing = byId.get(seed.id)
+    if (!existing) {
+      byId.set(seed.id, { id: seed.id, path: seed.path })
+      continue
+    }
+    if (!existing.path) {
+      byId.set(seed.id, { ...existing, path: seed.path })
+    }
+  }
+
+  return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id))
+}
+
+const resolveHumanDoc = (
+  packageId: string,
+  override?: string,
+  fmHuman?: string,
+  humanDocs: HumanDocMap = {},
+): string | undefined => {
+  if (override) return override
+  if (fmHuman) return fmHuman
+  if (humanDocs[packageId]) return humanDocs[packageId]
+  // common aliases: scoped package name tail, path segments
+  const aliases = [
+    packageId,
+    packageId.replace(/^@[^/]+\//, ''),
+    packageId.replace(/^os-/, ''),
+    packageId.replace(/-pattern$/, ''),
+  ]
+  for (const alias of aliases) {
+    if (humanDocs[alias]) return humanDocs[alias]
+  }
+  return undefined
+}
+
+export const buildLookup = (
+  config: DocBridgeConfigV1,
+  packages: readonly DiscoveredPackage[],
+  corpus: readonly CorpusDoc[],
+  indexOutFile: string,
+  humanDocs: HumanDocMap = {},
+  root = process.cwd(),
+): { lookup: IndexLookup; handoffs: Record<string, AgentHandoffV1> } => {
+  const ownership: Record<string, OwnershipRecord> = {}
+  const handoffs: Record<string, AgentHandoffV1> = {}
+  const strict = (config.gates?.preset ?? 'minimal') !== 'minimal'
+  const fmSeeds = new Map(
+    [...ownershipFromFrontmatter(corpus), ...ownershipFromCorpus(corpus)].map((seed) => [
+      seed.id,
+      seed,
+    ]),
+  )
+
+  for (const pkg of packages) {
+    const override = config.routing?.options?.ownership?.[pkg.id]
+    const fm = fmSeeds.get(pkg.id)
+    const agentDoc =
+      override?.agentDoc ??
+      fm?.agentDoc ??
+      guessAgentDocForPackage(corpus, pkg.id) ??
+      config.corpus.agent.index
+    const startHere = agentDoc ?? ''
+    const purpose = override?.purpose ?? fm?.purpose
+    const path = override?.path ?? fm?.path ?? pkg.path
+    const checks = [
+      ...(override?.checks ??
+        fm?.checks ??
+        defaultChecksForTarget(root, {
+          packageId: pkg.id,
+          packagePath: path,
+          ...(pkg.name ? { packageName: pkg.name } : {}),
+          strict,
+        })),
+    ]
+    const humanDoc = resolveHumanDoc(pkg.id, override?.humanDoc, fm?.humanDoc, humanDocs)
+    const record: OwnershipRecord = {
+      id: pkg.id,
+      path,
+      checks,
+      ...(override?.group ? { group: override.group } : {}),
+      ...(override?.layer ? { layer: override.layer } : {}),
+      ...(purpose ? { purpose } : {}),
+      ...(humanDoc ? { humanDoc } : {}),
+      ...(agentDoc ? { agentDoc } : {}),
+    }
+    ownership[pkg.id] = record
+
+    handoffs[pkg.id] = {
+      type: 'agent-handoff',
+      schemaVersion: 1,
+      source: indexOutFile,
+      target: {
+        type: 'package',
+        id: pkg.id,
+        path: record.path,
+        ...(record.group ? { group: record.group } : {}),
+        ...(record.layer ? { layer: record.layer } : {}),
+      },
+      startHere,
+      readBeforeEditing: [agentDoc, 'AGENTS.md'].filter((v, i, a): v is string =>
+        Boolean(v) && a.indexOf(v) === i,
+      ),
+      editRoots: [record.path],
+      checks: [...record.checks],
+      ...(record.humanDoc ? { humanDoc: record.humanDoc } : {}),
+      notes: record.purpose ? [record.purpose] : [],
+    }
+  }
+
+  const intents: Record<string, IntentRecord> = {}
+  for (const intent of config.routing?.options?.intents ?? []) {
+    intents[intent.id] = { id: intent.id, title: intent.title, paths: intent.paths }
+  }
+
+  const changes: Record<string, ChangeRecord> = {}
+  for (const change of config.routing?.options?.changes ?? []) {
+    changes[change.id] = {
+      id: change.id,
+      title: change.title,
+      startHere: change.startHere,
+      ...(change.relatedPackages ? { relatedPackages: change.relatedPackages } : {}),
+    }
+  }
+
+  return {
+    lookup: {
+      packages: packages.map((p) => p.id),
+      ownership,
+      intents,
+      changes,
+    },
+    handoffs,
+  }
+}

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

@@ -0,0 +1,137 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import { toPosix } from '../lib/paths.js'
+import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
+import { buildLookup, collectPackages } from './build-handoffs.js'
+import { renderCapabilitiesJson } from './capabilities.js'
+import { sha256NormalizedV1 } from './content-hash.js'
+import { renderLlmsTxt } from './llms-txt.js'
+import { scanHumanDocs } from './human-adapters/index.js'
+import { discoverPnpmPackages } from './plugins/pnpm-monorepo.js'
+import { scanAgentCorpus } from './scan-corpus.js'
+
+export type BuildIndexOptions = {
+  readonly root?: string
+  readonly config: DocBridgeConfigV1
+  readonly write?: boolean
+}
+
+export type BuildIndexResult = {
+  readonly index: DocBridgeIndexV1
+  readonly indexPath: string
+  readonly llmsTxtPath?: string
+  readonly capabilitiesPath?: string
+}
+
+const projectName = (root: string, config: DocBridgeConfigV1): string => {
+  if (config.project?.name) return config.project.name
+  try {
+    const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { name?: string }
+    if (pkg.name) return pkg.name
+  } catch {
+    // ignore
+  }
+  return toPosix(root.split('/').pop() ?? 'project')
+}
+
+const existingGeneratedAt = (indexPath: string, contentHash: string): string | undefined => {
+  try {
+    const index = JSON.parse(readFileSync(indexPath, 'utf8')) as {
+      contentHash?: unknown
+      generatedAt?: unknown
+    }
+    return index.contentHash === contentHash && typeof index.generatedAt === 'string'
+      ? index.generatedAt
+      : undefined
+  } catch {
+    return undefined
+  }
+}
+
+export const buildDocBridgeIndex = (opts: BuildIndexOptions): BuildIndexResult => {
+  const root = opts.root ?? process.cwd()
+  const config = opts.config
+  const write = opts.write ?? true
+  const outFile = config.index?.outFile ?? '.doc-bridge/index.json'
+  const indexPath = join(root, outFile)
+
+  const corpus = scanAgentCorpus(root, config)
+  const knowledge = corpus.map(({ absPath: _a, relPath: _r, frontmatter: _f, ...entry }) => entry)
+
+  const shouldDiscover =
+    config.routing?.plugin === 'pnpm-monorepo' ||
+    Boolean(config.routing?.options?.packages?.length) ||
+    config.routing?.plugin === 'npm-workspaces' ||
+    config.routing?.plugin === 'yarn-workspaces'
+
+  const discovered = shouldDiscover ? discoverPnpmPackages(root, config) : []
+  const packages = collectPackages(config, discovered, corpus)
+  const humanDocs = scanHumanDocs(root, config)
+
+  const { lookup, handoffs } = buildLookup(config, packages, corpus, outFile, humanDocs, root)
+
+  const hashPayload = {
+    schemaVersion: 1,
+    knowledge,
+    handoffs,
+    lookup,
+  }
+
+  const contentHash = sha256NormalizedV1(hashPayload)
+  const index: DocBridgeIndexV1 = {
+    schemaVersion: 1,
+    contentHash,
+    contentHashAlgo: 'sha256-normalized-v1',
+    generatedAt: existingGeneratedAt(indexPath, contentHash) ?? new Date().toISOString(),
+    project: { name: projectName(root, config), root: '.' },
+    knowledge,
+    handoffs,
+    lookup,
+  }
+
+  if (write) {
+    mkdirSync(dirname(indexPath), { recursive: true })
+    writeFileSync(indexPath, `${JSON.stringify(index, null, 2)}\n`, 'utf8')
+  }
+
+  let llmsTxtPath: string | undefined
+  let llmsTxtRelPath: string | undefined
+  if (config.index?.llmsTxt?.enabled !== false) {
+    const llmsOut = config.index?.llmsTxt?.outFile ?? 'llms.txt'
+    llmsTxtRelPath = toPosix(llmsOut)
+    llmsTxtPath = join(root, llmsOut)
+    if (write) {
+      writeFileSync(
+        llmsTxtPath,
+        renderLlmsTxt(config, knowledge, index.project?.name ?? 'project'),
+        'utf8',
+      )
+    }
+  }
+
+  let capabilitiesPath: string | undefined
+  if (config.index?.capabilities?.enabled !== false) {
+    const capabilitiesOut = config.index?.capabilities?.outFile ?? '.doc-bridge/capabilities.json'
+    capabilitiesPath = join(root, capabilitiesOut)
+    if (write) {
+      mkdirSync(dirname(capabilitiesPath), { recursive: true })
+      writeFileSync(
+        capabilitiesPath,
+        renderCapabilitiesJson(config, index, {
+          index: toPosix(outFile),
+          ...(llmsTxtRelPath ? { llmsTxt: llmsTxtRelPath } : {}),
+        }),
+        'utf8',
+      )
+    }
+  }
+
+  return {
+    index,
+    indexPath: toPosix(indexPath),
+    ...(llmsTxtPath ? { llmsTxtPath: toPosix(llmsTxtPath) } : {}),
+    ...(capabilitiesPath ? { capabilitiesPath: toPosix(capabilitiesPath) } : {}),
+  }
+}

package/src/index-builder/capabilities.ts

@@ -0,0 +1,37 @@
+import type { DocBridgeConfigV1 } from '../config/schema.js'
+import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
+import { PACKAGE_VERSION } from '../version.js'
+
+export const renderCapabilitiesJson = (
+  config: DocBridgeConfigV1,
+  index: DocBridgeIndexV1,
+  paths: { readonly index: string; readonly llmsTxt?: string },
+): string => {
+  const payload = {
+    schemaVersion: 1,
+    type: 'doc-bridge-capabilities',
+    package: '@agentskit/doc-bridge',
+    version: PACKAGE_VERSION,
+    project: index.project,
+    contentHash: index.contentHash,
+    artifacts: {
+      index: paths.index,
+      ...(paths.llmsTxt ? { llmsTxt: paths.llmsTxt } : {}),
+    },
+    capabilities: [
+      'index',
+      'query',
+      'search',
+      'agent-handoff',
+      'gates',
+      ...(config.surfaces?.mcp?.enabled === false ? [] : ['mcp']),
+      ...(config.corpus.human ? ['human-docs'] : []),
+    ],
+    surfaces: {
+      cli: config.surfaces?.cli,
+      mcp: config.surfaces?.mcp,
+    },
+  }
+
+  return `${JSON.stringify(payload, null, 2)}\n`
+}

package/src/index-builder/content-hash.ts

@@ -0,0 +1,19 @@
+import { createHash } from 'node:crypto'
+
+const sortValue = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(sortValue)
+  if (value && typeof value === 'object') {
+    const record = value as Record<string, unknown>
+    return Object.fromEntries(
+      Object.keys(record)
+        .sort()
+        .map((key) => [key, sortValue(record[key])]),
+    )
+  }
+  return value
+}
+
+export const sha256NormalizedV1 = (payload: unknown): string => {
+  const normalized = JSON.stringify(sortValue(payload))
+  return createHash('sha256').update(normalized, 'utf8').digest('hex')
+}