Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
feat(ok): Wave 2 link/graph routes native on Hono (PRD-7813) (#3244)
omar-inkeep86aa3e13bb52
diff --git a/knip.config.ts b/knip.config.tsindex f004e6bc3..13582ee18 100644--- a/knip.config.ts+++ b/knip.config.ts@@ -123,9 +123,7 @@ export default {'packages/server': {entry: ['src/**/*.test.ts', 'src/parse-worker.ts'],project: 'src/**',- ignoreDependencies: [- '@types/shell-quote',- ],+ ignoreDependencies: ['@types/shell-quote'],},'packages/cli': {entry: ['src/**/*.test.ts', 'scripts/*.ts', 'tests/**/*.ts', 'src/parse-worker.ts'],diff --git a/packages/app/src/server/hocuspocus-plugin.ts b/packages/app/src/server/hocuspocus-plugin.tsindex 0327ca7c5..1b84bb634 100644--- a/packages/app/src/server/hocuspocus-plugin.ts+++ b/packages/app/src/server/hocuspocus-plugin.ts@@ -224,8 +224,13 @@ export function hocuspocusPlugin(): Plugin {}});- const { hocuspocus, sessionManager, agentFocusBroadcaster, agentPresenceBroadcaster } =- currentSrv;+ const {+ hocuspocus,+ nativeApi,+ sessionManager,+ agentFocusBroadcaster,+ agentPresenceBroadcaster,+ } = currentSrv;// ACP thread host — the dev twin of boot.ts's construction (the// documented dual-upgrade-handler drift hazard applies to this whole@@ -375,6 +380,11 @@ export function hocuspocusPlugin(): Plugin {}// Method not GET/HEAD — fall through to 404.}+ // Natively-routed /api/* groups (ServerInstance.nativeApi) dispatch+ // BEFORE the legacy Hocuspocus hook — the dev twin of the Hono+ // app's above-the-catch-all mount in `mountMcpAndApi`. The shared+ // pipeline runs either way, so gate behavior is identical.+ if (await nativeApi.dispatch(req, res)) return;// biome-ignore lint/suspicious/noExplicitAny: Hocuspocus `hooks()` has no exported payload type for onRequestawait hocuspocus.hooks('onRequest', { request: req, response: res } as any);// Streaming NDJSON handlers call `writeHead(200)` and returndiff --git a/packages/app/tests/integration/attribution-sweep-coverage.test.ts b/packages/app/tests/integration/attribution-sweep-coverage.test.tsindex be015ba02..624f3679d 100644--- a/packages/app/tests/integration/attribution-sweep-coverage.test.ts+++ b/packages/app/tests/integration/attribution-sweep-coverage.test.ts@@ -16,6 +16,20 @@ import { describe, expect, test } from 'vitest';const API_EXT_PATH = join(import.meta.dirname, '../../../server/src/api-extension.ts');const source = readFileSync(API_EXT_PATH, 'utf8');+/**+ * Handlers and route records no longer all live in `api-extension.ts`: lifted+ * groups (`skills-sh-handlers.ts`, and native Wave 2 groups like+ * `http/link-graph-routes.ts`, which carry their OWN `const routes:` record)+ * must stay inside the sweep, mirroring `error-envelope-coverage.test.ts` —+ * otherwise a mutating handler added to a lifted file would ship without a+ * categorization decision.+ */+const HANDLER_SOURCES = [+ source,+ ...['skills-sh-handlers.ts', 'http/link-graph-routes.ts'].map((file) =>+ readFileSync(join(import.meta.dirname, '../../../server/src', file), 'utf8'),+ ),+];const ACTOR_HELPER_PATH = join(import.meta.dirname,'../../../server/src/extract-actor-identity.ts',@@ -416,34 +430,44 @@ const EXEMPT_HANDLERS = new Set([function extractHandlerBody(handlerName: string): string | null {// Legacy shape: `async function handle...(`. Migrated shape:// `const handle... = withValidation(...)`. Both must be supported as the- // cluster migrations land. Pick whichever appears first in the file.+ // cluster migrations land. Pick whichever source declares it (a lifted+ // handler is not in `api-extension.ts`), then whichever shape appears+ // first in that source.const fnDecl = `async function ${handlerName}(`;const constDecl = `const ${handlerName} = withValidation(`;- const fnIdx = source.indexOf(fnDecl);- const constIdx = source.indexOf(constDecl);+ const owner =+ HANDLER_SOURCES.find((text) => text.includes(fnDecl) || text.includes(constDecl)) ?? source;+ const fnIdx = owner.indexOf(fnDecl);+ const constIdx = owner.indexOf(constDecl);let start = -1;if (fnIdx !== -1) start = fnIdx;else if (constIdx !== -1) start = constIdx;if (start === -1) return null;- const nextFn = source.indexOf('\n async function handle', start + 1);- const nextConst = source.indexOf('\n const handle', start + 1);+ const nextFn = owner.indexOf('\n async function handle', start + 1);+ const nextConst = owner.indexOf('\n const handle', start + 1);// Bound the last handler at the route table so the onRequest extension// body (which uses `errorResponse(...)` for the /api/* Origin gate) is- // never folded into the handler slice.- const nextRoutes = source.indexOf('\n const routes:', start + 1);- const candidates = [nextFn, nextConst, nextRoutes].filter((i) => i !== -1);+ // never folded into the handler slice. Factory modules end their handler+ // run at the returned record instead, so bound on that too.+ const nextRoutes = owner.indexOf('\n const routes:', start + 1);+ const nextReturn = owner.indexOf('\n return {', start + 1);+ const candidates = [nextFn, nextConst, nextRoutes, nextReturn].filter((i) => i !== -1);const next = candidates.length === 0 ? -1 : Math.min(...candidates);- return source.slice(start, next === -1 ? source.length : next);+ return owner.slice(start, next === -1 ? owner.length : next);}function extractStaticRouteHandlerNames(): string[] {- const routesStart = source.indexOf('\n const routes:');- const enableTestRoutes = source.indexOf('\n if (enableTestRoutes)', routesStart);- const slice =- routesStart === -1- ? ''- : source.slice(routesStart, enableTestRoutes === -1 ? source.length : enableTestRoutes);- return [...slice.matchAll(/:\s*(handle\w+)/g)].map((m) => m[1]);+ // Every source's `const routes:` record participates — the legacy dispatch+ // record in `api-extension.ts` AND each native group's own record.+ return HANDLER_SOURCES.flatMap((text) => {+ const routesStart = text.indexOf('\n const routes:');+ if (routesStart === -1) return [];+ const enableTestRoutes = text.indexOf('\n if (enableTestRoutes)', routesStart);+ const nativeTable = text.indexOf('\n const table', routesStart);+ const bounds = [enableTestRoutes, nativeTable].filter((i) => i !== -1);+ const slice = text.slice(routesStart, bounds.length === 0 ? text.length : Math.min(...bounds));+ return [...slice.matchAll(/:\s*(handle\w+)/g)].map((m) => m[1]);+ });}describe('attribution sweep coverage (FR-5, D42)', () => {diff --git a/packages/app/tests/integration/conflict-gate-coverage.test.ts b/packages/app/tests/integration/conflict-gate-coverage.test.tsindex faca93c35..34a583047 100644--- a/packages/app/tests/integration/conflict-gate-coverage.test.ts+++ b/packages/app/tests/integration/conflict-gate-coverage.test.ts@@ -26,6 +26,19 @@ import { describe, expect, test } from 'vitest';const API_EXT_PATH = join(import.meta.dirname, '../../../server/src/api-extension.ts');const source = readFileSync(API_EXT_PATH, 'utf8');+/**+ * The conflict-refusal contract applies to any handler that writes user+ * content, regardless of which file it lives in — lifted route groups+ * (`skills-sh-handlers.ts`, native Wave 2 groups like+ * `http/link-graph-routes.ts` with their OWN `const routes:` record) stay+ * inside the scan, mirroring `error-envelope-coverage.test.ts`.+ */+const HANDLER_SOURCES = [+ source,+ ...['skills-sh-handlers.ts', 'http/link-graph-routes.ts'].map((file) =>+ readFileSync(join(import.meta.dirname, '../../../server/src', file), 'utf8'),+ ),+];/*** The 8 mutating handlers. Each@@ -321,34 +334,45 @@ const EXEMPT_HANDLERS = new Set([function extractHandlerBody(handlerName: string): string | null {// Same legacy vs migrated detection as the attribution-sweep meta-test,- // plus the `methodRouter({...})` dispatcher shape.+ // plus the `methodRouter({...})` dispatcher shape. Pick whichever source+ // declares it (a lifted handler is not in `api-extension.ts`).const fnDecl = `async function ${handlerName}(`;const constDecl = `const ${handlerName} = withValidation(`;const routerDecl = `const ${handlerName} = methodRouter(`;- const fnIdx = source.indexOf(fnDecl);- const constIdx = source.indexOf(constDecl);- const routerIdx = source.indexOf(routerDecl);+ const owner =+ HANDLER_SOURCES.find(+ (text) => text.includes(fnDecl) || text.includes(constDecl) || text.includes(routerDecl),+ ) ?? source;+ const fnIdx = owner.indexOf(fnDecl);+ const constIdx = owner.indexOf(constDecl);+ const routerIdx = owner.indexOf(routerDecl);let start = -1;if (fnIdx !== -1) start = fnIdx;else if (constIdx !== -1) start = constIdx;else if (routerIdx !== -1) start = routerIdx;if (start === -1) return null;- const nextFn = source.indexOf('\n async function handle', start + 1);- const nextConst = source.indexOf('\n const handle', start + 1);- const nextRoutes = source.indexOf('\n const routes:', start + 1);- const candidates = [nextFn, nextConst, nextRoutes].filter((i) => i !== -1);+ const nextFn = owner.indexOf('\n async function handle', start + 1);+ const nextConst = owner.indexOf('\n const handle', start + 1);+ const nextRoutes = owner.indexOf('\n const routes:', start + 1);+ // Factory modules end their handler run at the returned record.+ const nextReturn = owner.indexOf('\n return {', start + 1);+ const candidates = [nextFn, nextConst, nextRoutes, nextReturn].filter((i) => i !== -1);const next = candidates.length === 0 ? -1 : Math.min(...candidates);- return source.slice(start, next === -1 ? source.length : next);+ return owner.slice(start, next === -1 ? owner.length : next);}function extractStaticRouteHandlerNames(): string[] {- const routesStart = source.indexOf('\n const routes:');- const enableTestRoutes = source.indexOf('\n if (enableTestRoutes)', routesStart);- const slice =- routesStart === -1- ? ''- : source.slice(routesStart, enableTestRoutes === -1 ? source.length : enableTestRoutes);- return [...slice.matchAll(/:\s*(handle\w+)/g)].map((m) => m[1]);+ // Every source's `const routes:` record participates — the legacy dispatch+ // record in `api-extension.ts` AND each native group's own record.+ return HANDLER_SOURCES.flatMap((text) => {+ const routesStart = text.indexOf('\n const routes:');+ if (routesStart === -1) return [];+ const enableTestRoutes = text.indexOf('\n if (enableTestRoutes)', routesStart);+ const nativeTable = text.indexOf('\n const table', routesStart);+ const bounds = [enableTestRoutes, nativeTable].filter((i) => i !== -1);+ const slice = text.slice(routesStart, bounds.length === 0 ? text.length : Math.min(...bounds));+ return [...slice.matchAll(/:\s*(handle\w+)/g)].map((m) => m[1]);+ });}describe('conflict-gate coverage (FR9)', () => {diff --git a/packages/app/tests/integration/error-envelope-coverage.test.ts b/packages/app/tests/integration/error-envelope-coverage.test.tsindex 881cc106d..a53da8f4b 100644--- a/packages/app/tests/integration/error-envelope-coverage.test.ts+++ b/packages/app/tests/integration/error-envelope-coverage.test.ts@@ -28,7 +28,11 @@ const SERVER_SRC = join(import.meta.dirname, '../../../server/src');* `api-extension.ts` would otherwise escape these rules silently rather than* failing anything.*/-const HANDLER_SOURCES = ['api-extension.ts', 'skills-sh-handlers.ts'].map((file) => ({+const HANDLER_SOURCES = [+ 'api-extension.ts',+ 'skills-sh-handlers.ts',+ 'http/link-graph-routes.ts',+].map((file) => ({file,text: readFileSync(join(SERVER_SRC, file), 'utf8'),}));diff --git a/packages/app/tests/integration/test-harness.ts b/packages/app/tests/integration/test-harness.tsindex dca268447..9d4bd5259 100644--- a/packages/app/tests/integration/test-harness.ts+++ b/packages/app/tests/integration/test-harness.ts@@ -335,6 +335,7 @@ export async function createTestServer(options: CreateTestServerOptions = {}): Pconst mount = mountMcpAndApi({httpServer,hocuspocus: srv.hocuspocus,+ nativeApi: srv.nativeApi,mcpHttpHandler,log: getLogger('test-harness'),sessionManager: srv.sessionManager,@@ -1591,6 +1592,7 @@ export async function createRestartableServer(const mount = mountMcpAndApi({httpServer,hocuspocus: srv.hocuspocus,+ nativeApi: srv.nativeApi,mcpHttpHandler: undefined,log: getLogger('restartable-server'),sessionManager: srv.sessionManager,diff --git a/packages/core/src/bridge/bind-frontmatter-doc.ts b/packages/core/src/bridge/bind-frontmatter-doc.tsindex dfd95ef49..d7a845280 100644--- a/packages/core/src/bridge/bind-frontmatter-doc.ts+++ b/packages/core/src/bridge/bind-frontmatter-doc.ts@@ -1,4 +1,3 @@-import type * as Y from 'yjs';import type { Err, Ok, Result } from '../config/result.ts';import { type FrontmatterValidationError, toFrontmatterIssue } from '../frontmatter/errors.ts';diff --git a/packages/core/src/bridge/bridge-invariant.ts b/packages/core/src/bridge/bridge-invariant.tsindex 8bfdb40cd..005627195 100644--- a/packages/core/src/bridge/bridge-invariant.ts+++ b/packages/core/src/bridge/bridge-invariant.ts@@ -1,4 +1,3 @@-import { fnv1aDigest } from './hash-util.ts';export type BridgeInvariantSite = 'observer-b' | 'persistence' | 'test-harness';diff --git a/packages/core/src/bridge/compose.ts b/packages/core/src/bridge/compose.tsindex 2a597ec3d..f4cc8a286 100644--- a/packages/core/src/bridge/compose.ts+++ b/packages/core/src/bridge/compose.ts@@ -1,4 +1,3 @@-import { prependFrontmatter, stripFrontmatter } from '../extensions/frontmatter.ts';export type ComposeAdjustment = 'none' | 'body' | 'frontmatter' | 'unresolved';diff --git a/packages/core/src/bridge/doc-boundary-space.ts b/packages/core/src/bridge/doc-boundary-space.tsindex 01ef76a9f..8fb428b90 100644--- a/packages/core/src/bridge/doc-boundary-space.ts+++ b/packages/core/src/bridge/doc-boundary-space.ts@@ -1,4 +1,3 @@-import { FRONTMATTER_RE, stripFrontmatter } from '../extensions/frontmatter.ts';import { carriedEdgeEmpties, type DocEdgeEmpties } from '../markdown/doc-edge-blank-runs.ts';diff --git a/packages/core/src/bridge/growth-detect.ts b/packages/core/src/bridge/growth-detect.tsindex 463e89595..9d9c244b0 100644--- a/packages/core/src/bridge/growth-detect.ts+++ b/packages/core/src/bridge/growth-detect.ts@@ -1,4 +1,3 @@-const DEFAULT_MIN_SUBSTANTIVE_LINE_LENGTH = 16;export const DUPLICATION_GATE_MIN_LINE_LENGTH = 8;diff --git a/packages/core/src/bridge/intraline-predicate.ts b/packages/core/src/bridge/intraline-predicate.tsindex 0939885bb..c43fdd7e7 100644--- a/packages/core/src/bridge/intraline-predicate.ts+++ b/packages/core/src/bridge/intraline-predicate.ts@@ -1,4 +1,3 @@-export function rawLineCounts(doc: string): Map<string, number> {const counts = new Map<string, number>();for (const line of doc.split('\n')) {diff --git a/packages/core/src/bridge/merge-three-way.ts b/packages/core/src/bridge/merge-three-way.tsindex c0dc65705..251560a35 100644--- a/packages/core/src/bridge/merge-three-way.ts+++ b/packages/core/src/bridge/merge-three-way.ts@@ -65,7 +65,6 @@ export function tryLineLevelCombine(return { clean: true, merged };}-export type BridgeMergeContentLossSide = 'user' | 'agent';export type BridgeMergeContentLossWhich = 'substring' | 'order' | 'growth';diff --git a/packages/core/src/bridge/normalize.ts b/packages/core/src/bridge/normalize.tsindex dcc5b0690..01ac80099 100644--- a/packages/core/src/bridge/normalize.ts+++ b/packages/core/src/bridge/normalize.ts@@ -1,4 +1,3 @@-import { stripFrontmatter } from '../extensions/frontmatter.ts';import { bodyEdgeEmpties } from './doc-boundary-space.ts';diff --git a/packages/core/src/bridge/pm-structural-equivalence.ts b/packages/core/src/bridge/pm-structural-equivalence.tsindex 0be5203e4..754dc5cc2 100644--- a/packages/core/src/bridge/pm-structural-equivalence.ts+++ b/packages/core/src/bridge/pm-structural-equivalence.ts@@ -32,7 +32,6 @@ const BR_SENTINEL: PmStructuralNode = { type: '__br__' };const BR_LITERAL_RE = /^<br\s*\/?>$/i;-interface DegradeEntry {readonly label: string;readonly severity: ToleranceClassSeverity;@@ -128,7 +127,6 @@ export interface ComparePmStructuralOptions {ignoreAttrs?: (attrKey: string) => boolean;}-/** Rebuild a node with `fn` applied to each child; identity when childless.* Shared by the degrade canonicalizers so none re-implements the walk. */function mapChildren(@@ -250,7 +248,6 @@ function applyDegrades(tree: PmStructuralNode): {return { normalized: current, fired };}-export function comparePmStructural(expected: PmStructuralNode,actual: PmStructuralNode,diff --git a/packages/core/src/bridge/subsequence.ts b/packages/core/src/bridge/subsequence.tsindex dca644141..af20de1e2 100644--- a/packages/core/src/bridge/subsequence.ts+++ b/packages/core/src/bridge/subsequence.ts@@ -1,4 +1,3 @@-/** True when `needle` is a subsequence of `haystack` (two-pointer, O(n+m)):* insertions in `haystack` are free; any dropped or substituted `needle` byte* fails. */diff --git a/packages/core/src/markdown/callout-transformer.ts b/packages/core/src/markdown/callout-transformer.tsindex a363dfd54..83d47404a 100644--- a/packages/core/src/markdown/callout-transformer.ts+++ b/packages/core/src/markdown/callout-transformer.ts@@ -1,4 +1,3 @@-import type { Blockquote, Paragraph, Root } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/code-fence.ts b/packages/core/src/markdown/code-fence.tsindex 4499dbc92..9807a7e82 100644--- a/packages/core/src/markdown/code-fence.ts+++ b/packages/core/src/markdown/code-fence.ts@@ -1,4 +1,3 @@-export function selectFenceChar(info: string): '`' | '~' {return info.includes('`') ? '~' : '`';}diff --git a/packages/core/src/markdown/comment-promoter.ts b/packages/core/src/markdown/comment-promoter.tsindex 34704165b..7415c474a 100644--- a/packages/core/src/markdown/comment-promoter.ts+++ b/packages/core/src/markdown/comment-promoter.ts@@ -1,4 +1,3 @@-import type { Nodes, Paragraph, PhrasingContent, Root, RootContent, Text } from 'mdast';import { SKIP, visit } from 'unist-util-visit';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/dedent-block-jsx-close.ts b/packages/core/src/markdown/dedent-block-jsx-close.tsindex b6299a948..ece5c02a1 100644--- a/packages/core/src/markdown/dedent-block-jsx-close.ts+++ b/packages/core/src/markdown/dedent-block-jsx-close.ts@@ -1,4 +1,3 @@-import { findFencedRegions, isInsideFence } from './fence-regions.ts';const INDENTED_BLOCK_JSX_CLOSE_RE = /^([ ]{1,3})(<\/[A-Z][A-Za-z0-9_]*\s*>)([ \t]*)$/gm;diff --git a/packages/core/src/markdown/details-accordion-promoter.ts b/packages/core/src/markdown/details-accordion-promoter.tsindex acd398aa6..54774764a 100644--- a/packages/core/src/markdown/details-accordion-promoter.ts+++ b/packages/core/src/markdown/details-accordion-promoter.ts@@ -1,4 +1,3 @@-import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/div-align-promoter.ts b/packages/core/src/markdown/div-align-promoter.tsindex ba9b56384..43ecdc709 100644--- a/packages/core/src/markdown/div-align-promoter.ts+++ b/packages/core/src/markdown/div-align-promoter.ts@@ -1,4 +1,3 @@-import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';import type { MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/fence-regions.ts b/packages/core/src/markdown/fence-regions.tsindex 4513da9bb..6d3f3643e 100644--- a/packages/core/src/markdown/fence-regions.ts+++ b/packages/core/src/markdown/fence-regions.ts@@ -1,4 +1,3 @@-const FENCE_RE = /^(`{3,}|~{3,})/gm;export function findFencedRegions(src: string): Array<[number, number]> {diff --git a/packages/core/src/markdown/fixtures/index.ts b/packages/core/src/markdown/fixtures/index.tsindex 6931623c7..00f5771ee 100644--- a/packages/core/src/markdown/fixtures/index.ts+++ b/packages/core/src/markdown/fixtures/index.ts@@ -1,4 +1,3 @@-import { readFileSync } from 'node:fs';import { dirname, resolve } from 'node:path';import { fileURLToPath } from 'node:url';@@ -9,7 +8,6 @@ function fixturePath(...segments: string[]): string {return resolve(FIXTURES_DIR, ...segments);}-interface GfmExample {section: string;markdown: string;@@ -19,7 +17,6 @@ export function loadGfmExamples(): GfmExample[] {return JSON.parse(readFileSync(fixturePath('gfm', 'examples.json'), 'utf8')) as GfmExample[];}-interface MdxCrashEntry {id: string;input: string;@@ -71,7 +68,6 @@ export function loadLargeEmbedFixtures(): LargeEmbedFixture[] {) as LargeEmbedFixture[];}-export function loadPrd6955Before(): string {return readFileSync(fixturePath('regression', 'prd-6955-before.md'), 'utf8');}@@ -80,7 +76,6 @@ export function loadPrd6955CorruptedTriplicated(): string {return readFileSync(fixturePath('regression', 'prd-6955-corrupted-triplicated.md'), 'utf8');}-export interface NgPinnedCase {id: string;name: string;@@ -97,7 +92,6 @@ export function loadNgPinnedCases(): NgPinnedCase[] {) as NgPinnedCase[];}-export function loadLargeRealistic(): string {return readFileSync(fixturePath('perf', 'large-realistic.md'), 'utf8');}diff --git a/packages/core/src/markdown/fixtures/perf/generate.ts b/packages/core/src/markdown/fixtures/perf/generate.tsindex daa3ef82b..8b1eb8519 100644--- a/packages/core/src/markdown/fixtures/perf/generate.ts+++ b/packages/core/src/markdown/fixtures/perf/generate.ts@@ -1,4 +1,3 @@-import { writeFileSync } from 'node:fs';import { dirname, resolve } from 'node:path';import { fileURLToPath } from 'node:url';@@ -11,7 +10,6 @@ const BASELINE_ONLY_COUNTS = [500, 2500] as const;const SEED = 0xf1de1117;-function mulberry32(seed: number): () => number {let a = seed >>> 0;return () => {@@ -38,7 +36,6 @@ function pickWeighted<T>(rand: () => number, items: readonly [T, number][]): T {return items[items.length - 1][0];}-const WORDS = ['lorem','ipsum',@@ -156,7 +153,6 @@ function mdxBlock(rand: () => number): string {return `<${name}>\n\n${sentence(rand)}\n\n</${name}>`;}-type BlockKind = 'paragraph' | 'heading' | 'list' | 'code' | 'table' | 'mdx';const MIX: readonly [BlockKind, number][] = [@@ -195,7 +191,6 @@ function generateDocument(blockCount: number, seed: number): string {return `${blocks.join('\n\n')}\n`;}-function main(): void {for (const count of [...BLOCK_COUNTS, ...BASELINE_ONLY_COUNTS]) {const doc = generateDocument(count, SEED);diff --git a/packages/core/src/markdown/guard-flanking-matrix.ts b/packages/core/src/markdown/guard-flanking-matrix.tsindex 32c055c5b..420dc0fe5 100644--- a/packages/core/src/markdown/guard-flanking-matrix.ts+++ b/packages/core/src/markdown/guard-flanking-matrix.ts@@ -7,7 +7,6 @@ import {import { BACKSLASH_GUARD_SUBSTITUTIONS, encodeBackslashEscapes } from './backslash-escape-guard.ts';import { ENTITY_REF_GUARD_SUBSTITUTIONS, encodeEntityRefs } from './entity-ref-guard.ts';-export const ATTENTION_DELIMITERS = ['*', '_', '**', '~~', '=='] as const;export type FlankClass = 'whitespace' | 'punctuation' | 'other';diff --git a/packages/core/src/markdown/handler-shadow-audit.ts b/packages/core/src/markdown/handler-shadow-audit.tsindex 283913255..2653473da 100644--- a/packages/core/src/markdown/handler-shadow-audit.ts+++ b/packages/core/src/markdown/handler-shadow-audit.ts@@ -1,4 +1,3 @@-export interface HandlerShadowWitness {input: string;expect: 'byte' | 'byte-and-reparse-type';diff --git a/packages/core/src/markdown/highlight-promoter.ts b/packages/core/src/markdown/highlight-promoter.tsindex 5d1000cc4..da0a81d23 100644--- a/packages/core/src/markdown/highlight-promoter.ts+++ b/packages/core/src/markdown/highlight-promoter.ts@@ -1,4 +1,3 @@-import type { Nodes, Parent, PhrasingContent, Root, Text } from 'mdast';import type { MdxJsxTextElement } from 'mdast-util-mdx';import { SKIP, visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/html-to-mdast.ts b/packages/core/src/markdown/html-to-mdast.tsindex 9681c0056..787315157 100644--- a/packages/core/src/markdown/html-to-mdast.ts+++ b/packages/core/src/markdown/html-to-mdast.ts@@ -1,4 +1,3 @@-import type { Element as HastElement, Root as HastRoot } from 'hast';import type { List, Nodes as MdastNodes, Root as MdastRoot } from 'mdast';import rehypeParse from 'rehype-parse';@@ -129,8 +128,7 @@ export function htmlToMdast(html: string, options?: HtmlToMdastOptions): MdastRothrow new HtmlPayloadTooLargeError(html.length, maxBytes);}- const processor = unified()- .use(rehypeParse, { fragment: true });+ const processor = unified().use(rehypeParse, { fragment: true });for (const plugin of cleanupPlugins) {processor.use(plugin);diff --git a/packages/core/src/markdown/image-promoter.ts b/packages/core/src/markdown/image-promoter.tsindex 994eb6917..706fa9afb 100644--- a/packages/core/src/markdown/image-promoter.ts+++ b/packages/core/src/markdown/image-promoter.ts@@ -1,4 +1,3 @@-import type { Image, Paragraph, Root } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/index.ts b/packages/core/src/markdown/index.tsindex 69221627d..9075aa7f1 100644--- a/packages/core/src/markdown/index.ts+++ b/packages/core/src/markdown/index.ts@@ -1,4 +1,3 @@-import {type FromProseMirrorOptions,fromPmMark,@@ -207,7 +206,6 @@ export class MarkdownManager {}}-const registry = createRegistry();function destructureAttrs(@@ -256,7 +254,6 @@ function destructureAttrs(return result;}-function hasDirtyDescendant(node: PmNode): boolean {let found = false;node.descendants((child) => {@@ -279,7 +276,6 @@ function effectiveDirty(node: PmNode, freshnessChecker?: StructuralFreshnessChecreturn freshnessChecker ? freshnessChecker.isDiverged(node.toJSON()) : false;}-function isEmptyMdastParagraph(node: MdastNodes): boolean {if (node.type !== 'paragraph') return false;const children = node.children ?? [];@@ -348,7 +344,6 @@ function extractTextFromMdastNodes(nodes: MdastNodes[]): string {return out;}-import {AUDIO_EXTENSIONS,FILE_ATTACHMENT_EXTENSIONS,@@ -601,7 +596,6 @@ function buildMdastToPmHandlers(}));}-if (m.emphasis) {handlers.emphasis = toPmMark(m.emphasis, (node: Emphasis) => ({sourceDelimiter: node.data?.sourceDelimiter ?? '*',@@ -682,7 +676,6 @@ function buildMdastToPmHandlers(}));}-if (m.link) {const sourceLiteralMark = m.sourceLiteral;handlers.link = (node: Link, _parent: MdastParent, state: MdastToPmState) => {@@ -980,7 +973,6 @@ function buildMdastToPmHandlers(};}-const blockUnknownHandler = (node: {type: string;position?: { start: { offset: number }; end: { offset: number } };@@ -1106,7 +1098,6 @@ function buildMdastToPmHandlers(return handlers as RemarkProseMirrorOptions['handlers'];}-function buildPmToMdastHandlers(schema: Schema,freshness: FreshnessCheckerHolder,diff --git a/packages/core/src/markdown/lint/applies-to.ts b/packages/core/src/markdown/lint/applies-to.tsindex b79e9aef7..fa0be9e86 100644--- a/packages/core/src/markdown/lint/applies-to.ts+++ b/packages/core/src/markdown/lint/applies-to.ts@@ -1,4 +1,3 @@-import picomatch from 'picomatch';import { SUPPORTED_DOC_EXTENSIONS } from '../../constants/doc-extensions.ts';diff --git a/packages/core/src/markdown/lint/config-files.ts b/packages/core/src/markdown/lint/config-files.tsindex 94b34dee1..312c9c74b 100644--- a/packages/core/src/markdown/lint/config-files.ts+++ b/packages/core/src/markdown/lint/config-files.ts@@ -1,4 +1,3 @@-const MARKDOWNLINT_JSON_CONFIG_FILES: ReadonlySet<string> = new Set(['.markdownlint.json','.markdownlint.jsonc',diff --git a/packages/core/src/markdown/lint/config-schemas.ts b/packages/core/src/markdown/lint/config-schemas.tsindex e413367ef..0ba33b7d8 100644--- a/packages/core/src/markdown/lint/config-schemas.ts+++ b/packages/core/src/markdown/lint/config-schemas.ts@@ -38,7 +38,6 @@ const fullPluginShape = Object.fromEntries(LINT_PLUGINS.map((plugin) => [plugin.id, plugin.sliceSchema]),) as z.ZodRawShape;-export const LinterConfigSchema = z.object({enabled: z.boolean(),plugins: z.object(fullPluginShape),diff --git a/packages/core/src/markdown/lint/default-config.ts b/packages/core/src/markdown/lint/default-config.tsindex a51f2ffb0..d48eea5e4 100644--- a/packages/core/src/markdown/lint/default-config.ts+++ b/packages/core/src/markdown/lint/default-config.ts@@ -6,7 +6,6 @@ export const DEFAULT_MARKDOWNLINT_CONFIG: Record<string, MarkdownlintRuleSettingMD013: false,};-export function resolveMarkdownlintConfig(rules: Record<string, MarkdownlintRuleSetting> | undefined,): Configuration {diff --git a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts b/packages/core/src/markdown/lint/frontmatter-schema-edit.tsindex 9c9542661..ef478e268 100644--- a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts+++ b/packages/core/src/markdown/lint/frontmatter-schema-edit.ts@@ -1,4 +1,3 @@-import { CANONICAL_SCHEMA_DIALECT_URIS, DEFAULT_SCHEMA_DIALECT } from './frontmatter-validate.ts';export interface FrontmatterFieldConstraint {diff --git a/packages/core/src/markdown/lint/frontmatter-validate.ts b/packages/core/src/markdown/lint/frontmatter-validate.tsindex b96d19182..0d4c9a0df 100644--- a/packages/core/src/markdown/lint/frontmatter-validate.ts+++ b/packages/core/src/markdown/lint/frontmatter-validate.ts@@ -1,4 +1,3 @@-import Ajv, { type ValidateFunction } from 'ajv';import Ajv2019 from 'ajv/dist/2019.js';import Ajv2020 from 'ajv/dist/2020.js';diff --git a/packages/core/src/markdown/lint/index.ts b/packages/core/src/markdown/lint/index.tsindex 48d260ed6..00d08265a 100644--- a/packages/core/src/markdown/lint/index.ts+++ b/packages/core/src/markdown/lint/index.ts@@ -1,4 +1,3 @@-import { LINT_PLUGINS, type LinterConfig } from './plugins.ts';import type { LintDiagnostic } from './types.ts';diff --git a/packages/core/src/markdown/lint/plugins.ts b/packages/core/src/markdown/lint/plugins.tsindex be5871ed9..5e832aa19 100644--- a/packages/core/src/markdown/lint/plugins.ts+++ b/packages/core/src/markdown/lint/plugins.ts@@ -1,4 +1,3 @@-import { z } from 'zod';import { DEFAULT_MARKDOWNLINT_CONFIG, resolveMarkdownlintConfig } from './default-config.ts';import {@@ -14,7 +13,6 @@ import {type MarkdownlintSlice,} from './types.ts';-const MarkdownlintRuleSettingSchema = z.union([z.boolean(),z.enum(MARKDOWNLINT_RULE_SEVERITIES),diff --git a/packages/core/src/markdown/lint/types.ts b/packages/core/src/markdown/lint/types.tsindex 833c3a727..3918e657c 100644--- a/packages/core/src/markdown/lint/types.ts+++ b/packages/core/src/markdown/lint/types.ts@@ -1,4 +1,3 @@-export const LINT_PLUGIN_IDS = ['markdownlint', 'frontmatter'] as const;export type LintPluginId = (typeof LINT_PLUGIN_IDS)[number];@@ -72,7 +71,6 @@ export interface FrontmatterSlice {schemas: ResolvedFrontmatterSchemaEntry[];}-interface RuleOptionSpecBase {key: string;description: string;diff --git a/packages/core/src/markdown/lint/validation-counts.ts b/packages/core/src/markdown/lint/validation-counts.tsindex 437cc539a..98238656e 100644--- a/packages/core/src/markdown/lint/validation-counts.ts+++ b/packages/core/src/markdown/lint/validation-counts.ts@@ -1,4 +1,3 @@-export interface ValidationSourceCounts {errorCount: number;warningCount: number;diff --git a/packages/core/src/markdown/math-promoter.ts b/packages/core/src/markdown/math-promoter.tsindex bd79424c7..a5b511f25 100644--- a/packages/core/src/markdown/math-promoter.ts+++ b/packages/core/src/markdown/math-promoter.ts@@ -1,4 +1,3 @@-import type { Code, Root } from 'mdast';import type { Math as MdastMath } from 'mdast-util-math';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';diff --git a/packages/core/src/markdown/mdast-to-hast-handlers.ts b/packages/core/src/markdown/mdast-to-hast-handlers.tsindex 00fbc0035..ed89371d0 100644--- a/packages/core/src/markdown/mdast-to-hast-handlers.ts+++ b/packages/core/src/markdown/mdast-to-hast-handlers.ts@@ -1,4 +1,3 @@-import type { Comment, Element, ElementContent, Properties } from 'hast';import type { FootnoteDefinition, FootnoteReference } from 'mdast';import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx';diff --git a/packages/core/src/markdown/mdast-to-html.ts b/packages/core/src/markdown/mdast-to-html.tsindex df788a80d..8ce2b2492 100644--- a/packages/core/src/markdown/mdast-to-html.ts+++ b/packages/core/src/markdown/mdast-to-html.ts@@ -1,4 +1,3 @@-import type { Element, Root as HastRoot, Text as HastText } from 'hast';import type { Root as MdastRoot, Text as MdastText } from 'mdast';import type { Handler } from 'mdast-util-to-hast';diff --git a/packages/core/src/markdown/merged-walker.ts b/packages/core/src/markdown/merged-walker.tsindex fa3cfcd86..bfd7e3109 100644--- a/packages/core/src/markdown/merged-walker.ts+++ b/packages/core/src/markdown/merged-walker.ts@@ -1,4 +1,3 @@-import type { Nodes, Parent, Root } from 'mdast';import { SKIP, visit } from 'unist-util-visit';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/mermaid-promoter.ts b/packages/core/src/markdown/mermaid-promoter.tsindex 17ed2b829..1a897fca8 100644--- a/packages/core/src/markdown/mermaid-promoter.ts+++ b/packages/core/src/markdown/mermaid-promoter.ts@@ -1,4 +1,3 @@-import type { Code, Root } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/parse-with-fallback.ts b/packages/core/src/markdown/parse-with-fallback.tsindex 4aa0490c4..d988f4b8b 100644--- a/packages/core/src/markdown/parse-with-fallback.ts+++ b/packages/core/src/markdown/parse-with-fallback.ts@@ -168,7 +168,6 @@ export function parseRecursive(}}-interface VFilePlace {offset?: number;start?: { offset?: number };@@ -187,7 +186,6 @@ function extractErrorOffset(err: unknown): number | undefined {return undefined;}-interface Region {start: number;end: number;@@ -211,7 +209,6 @@ function nearestBlankLineAfter(src: string, offset: number): number | null {return null;}-export interface TagEvent {kind: 'open' | 'close' | 'self-close';name: string;@@ -358,7 +355,6 @@ function findFallbackRegion(src: string, errorOffset: number): Region {return { start: blockStart, end: blockEnd };}-interface SourceBlock {src: string;start: number;@@ -456,7 +452,6 @@ function tryPerBlockFallback(};}-function wholeDocRawText(source: string): JSONContent {return {type: 'doc',diff --git a/packages/core/src/markdown/parser-drop-closure.ts b/packages/core/src/markdown/parser-drop-closure.tsindex 43d420187..e6ab4fd57 100644--- a/packages/core/src/markdown/parser-drop-closure.ts+++ b/packages/core/src/markdown/parser-drop-closure.ts@@ -1,4 +1,3 @@-export type DroppedTokenAdjudication =| {kind: 'format-dof-axis';diff --git a/packages/core/src/markdown/pipeline.ts b/packages/core/src/markdown/pipeline.tsindex 5af2f05f5..449e6f12f 100644--- a/packages/core/src/markdown/pipeline.ts+++ b/packages/core/src/markdown/pipeline.ts@@ -1,4 +1,3 @@-import {type FromProseMirrorOptions,fromProseMirror,diff --git a/packages/core/src/markdown/position-aware-join.ts b/packages/core/src/markdown/position-aware-join.tsindex ccf06e94d..91cdf658f 100644--- a/packages/core/src/markdown/position-aware-join.ts+++ b/packages/core/src/markdown/position-aware-join.ts@@ -1,4 +1,3 @@-import type { Join } from 'mdast-util-to-markdown';import type { Position } from 'unist';import { isBlankLineParagraph } from './zero-emission-blocks.ts';diff --git a/packages/core/src/markdown/position-slice.ts b/packages/core/src/markdown/position-slice.tsindex e5b4c9eba..0f399d34c 100644--- a/packages/core/src/markdown/position-slice.ts+++ b/packages/core/src/markdown/position-slice.ts@@ -1,4 +1,3 @@-import type { Nodes, Root } from 'mdast';import { visit } from 'unist-util-visit';import type { VFile } from 'vfile';@@ -477,8 +476,7 @@ export function applyPositionSliceToNode(const first = source[startOff];if (first !== '[' && first !== '<' && !node.title) {node.data.sourceStyle = 'gfm-autolink';- }- else if (first === '[') {+ } else if (first === '[') {const slice = source.slice(startOff, endOff);const closeBracketIdx = slice.lastIndexOf('](');if (closeBracketIdx !== -1) {diff --git a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.tsindex ca225ce9b..db10fa54b 100644--- a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts+++ b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts@@ -1,4 +1,3 @@-import type { Comment, Element, Root, Text } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.tsindex 3a2524a9a..34068d103 100644--- a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts@@ -1,4 +1,3 @@-import type { Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.tsindex 2279a0189..93151d43b 100644--- a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts@@ -1,4 +1,3 @@-import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.tsindex a0f467c42..188f02d83 100644--- a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts@@ -1,4 +1,3 @@-import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.tsindex 4e8542a21..4ba2c3418 100644--- a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts@@ -1,4 +1,3 @@-import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.tsindex a3c96b24a..1a74b1272 100644--- a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts@@ -1,4 +1,3 @@-import type { Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.tsindex e95cf43d6..de35e7b79 100644--- a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts@@ -1,4 +1,3 @@-import type { Comment, Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.tsindex ffdb4d5b5..b4be1b2ea 100644--- a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts@@ -1,4 +1,3 @@-import type { Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.tsindex e2a96d1a7..3c8d88b7c 100644--- a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts@@ -1,4 +1,3 @@-import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/resolve-image-url.ts b/packages/core/src/markdown/resolve-image-url.tsindex 0389575ac..cf2c9da8e 100644--- a/packages/core/src/markdown/resolve-image-url.ts+++ b/packages/core/src/markdown/resolve-image-url.ts@@ -1,4 +1,3 @@-import { isRelativeUrl } from './safe-url.ts';function isDevDiagnosticContext(): boolean {diff --git a/packages/core/src/markdown/safe-url.ts b/packages/core/src/markdown/safe-url.tsindex 8be632ba4..4d3250d3a 100644--- a/packages/core/src/markdown/safe-url.ts+++ b/packages/core/src/markdown/safe-url.ts@@ -1,4 +1,3 @@-export const SAFE_URL_SCHEMES = ['https', 'http', 'mailto', 'tel', 'ftp', 'sms'] as const;const SCHEME_ALT = SAFE_URL_SCHEMES.map((s) => `${s}:`).join('|');diff --git a/packages/core/src/markdown/serialize-fidelity.test-helper.ts b/packages/core/src/markdown/serialize-fidelity.test-helper.tsindex 96304e7a5..0dd54070e 100644--- a/packages/core/src/markdown/serialize-fidelity.test-helper.ts+++ b/packages/core/src/markdown/serialize-fidelity.test-helper.ts@@ -1,4 +1,3 @@-import type { JSONContent } from '@tiptap/core';import type { Nodes } from 'mdast';import { expect } from 'vitest';diff --git a/packages/core/src/markdown/serialize-helpers.ts b/packages/core/src/markdown/serialize-helpers.tsindex 93798cf83..7cac5b042 100644--- a/packages/core/src/markdown/serialize-helpers.ts+++ b/packages/core/src/markdown/serialize-helpers.ts@@ -1,4 +1,3 @@-import type { Node as PmNode } from '@tiptap/pm/model';import type {MdxJsxAttribute,diff --git a/packages/core/src/markdown/single-dollar-math-promoter.ts b/packages/core/src/markdown/single-dollar-math-promoter.tsindex 8c08b7a04..b012a5aff 100644--- a/packages/core/src/markdown/single-dollar-math-promoter.ts+++ b/packages/core/src/markdown/single-dollar-math-promoter.ts@@ -1,4 +1,3 @@-import type { PhrasingContent, Root, Text } from 'mdast';import type { InlineMath } from 'mdast-util-math';import { SKIP, visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/to-markdown-handlers.ts b/packages/core/src/markdown/to-markdown-handlers.tsindex 959cc0bd2..3e79f8cb6 100644--- a/packages/core/src/markdown/to-markdown-handlers.ts+++ b/packages/core/src/markdown/to-markdown-handlers.ts@@ -1,4 +1,3 @@-import type { Nodes, Parents } from 'mdast';import type { MdxJsxAttribute, MdxJsxExpressionAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import type { Handle, Info, State } from 'mdast-util-to-markdown';diff --git a/packages/core/src/markdown/underline-promoter.ts b/packages/core/src/markdown/underline-promoter.tsindex 6e6d73400..0f1b0f27d 100644--- a/packages/core/src/markdown/underline-promoter.ts+++ b/packages/core/src/markdown/underline-promoter.ts@@ -1,4 +1,3 @@-import type { Nodes, Parent, Root } from 'mdast';import type { MdxJsxTextElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/unknown-mdast-guard.ts b/packages/core/src/markdown/unknown-mdast-guard.tsindex 932d7d2a8..1a082bda7 100644--- a/packages/core/src/markdown/unknown-mdast-guard.ts+++ b/packages/core/src/markdown/unknown-mdast-guard.ts@@ -1,4 +1,3 @@-import type { Root as MdastRoot } from 'mdast';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/whitespace-char-ref.ts b/packages/core/src/markdown/whitespace-char-ref.tsindex ac9f5239b..d578476a7 100644--- a/packages/core/src/markdown/whitespace-char-ref.ts+++ b/packages/core/src/markdown/whitespace-char-ref.ts@@ -1,4 +1,3 @@-const INLINE_WHITESPACE_BY_CODE: ReadonlyMap<number, string> = new Map([[0x20, ' '],[0x09, '\t'],diff --git a/packages/core/src/markdown/wiki-link-micromark.ts b/packages/core/src/markdown/wiki-link-micromark.tsindex afd9936fe..6dad26200 100644--- a/packages/core/src/markdown/wiki-link-micromark.ts+++ b/packages/core/src/markdown/wiki-link-micromark.ts@@ -17,7 +17,6 @@ declare module 'micromark-util-types' {}}-const CODE_BANG = 33; // !const CODE_LBRACKET = 91; // [const CODE_RBRACKET = 93; // ]@@ -261,7 +260,6 @@ export function wikiLinkSyntax(): Extension {};}-function enterWikiLink(this: CompileContext, token: Token) {this.enter({@@ -387,7 +385,6 @@ export const wikiLinkToMarkdown: {unsafe: [{ character: '[', inConstruct: ['phrasing'] }],};-const MICROMARK_EXT = wikiLinkSyntax();export function remarkWikiLink(this: Processor) {diff --git a/packages/server/src/api-extension.test-helper.ts b/packages/server/src/api-extension.test-helper.tsindex 965dfd85a..a34a6177c 100644--- a/packages/server/src/api-extension.test-helper.ts+++ b/packages/server/src/api-extension.test-helper.ts@@ -1,3 +1,4 @@+import type { IncomingMessage, ServerResponse } from 'node:http';import type { ApiExtensionOptions } from './api-extension.ts';import { createApiExtension as createApiExtensionBase } from './api-extension.ts';import type { BacklinkIndex } from './backlink-index.ts';@@ -219,11 +220,24 @@ export function createApiExtension(},): ReturnType<typeof createApiExtensionBase> {const { backlinkIndex, tagIndex, derivedDocumentIndex, ...apiOptions } = options;- return createApiExtensionBase({+ const extension = createApiExtensionBase({...apiOptions,durabilityState: new DocumentDurabilityState(),derivedDocumentIndex:derivedDocumentIndex ??createLegacyDerivedIndexPort(backlinkIndex, tagIndex, options.signalChannel),});+ // Mirror the production composition (Hono native mount ABOVE the strangler+ // catch-all): natively-routed groups dispatch first, everything else flows+ // through the legacy onRequest hook. Tests that drive `ext.onRequest`+ // directly keep reaching ported routes through the same shared pipeline.+ const legacyOnRequest = extension.onRequest?.bind(extension);+ return {+ ...extension,+ async onRequest(payload: { request: IncomingMessage; response: ServerResponse }) {+ if (await extension.nativeApi.dispatch(payload.request, payload.response)) return;+ // biome-ignore lint/suspicious/noExplicitAny: Hocuspocus `onRequest` has no exported payload type+ await legacyOnRequest?.(payload as any);+ },+ };}diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.tsindex 844015fa6..64af002bb 100644--- a/packages/server/src/api-extension.ts+++ b/packages/server/src/api-extension.ts@@ -47,13 +47,10 @@ import {AgentWriteSuccessSchema,ApiConfigSuccessSchema,applyPatchToFm,- BacklinkCountsSuccessSchema,- BacklinksSuccessSchema,type BatchEntryError,BranchInfoResponseSchema,CheckoutRequestSchema,CheckoutResponseSchema,- CLIENT_VERSION_HEADER,ClientLogsRequestSchema,ClientLogsSuccessSchema,CONFIG_DOC_NAME_OKIGNORE,@@ -72,7 +69,6 @@ import {DEFAULT_EMBEDDINGS_MODEL,DEFAULT_LINKS_VALIDATION,DEFAULT_LINTER_CONFIG,- DeadLinksSuccessSchema,DeletePathRequestSchema,DeletePathSuccessSchema,type DiskEditReconciledWarning,@@ -91,7 +87,6 @@ import {FolderConfigGetSuccessSchema,FolderConfigPutRequestSchema,FolderConfigPutSuccessSchema,- ForwardLinksSuccessSchema,FrontmatterPatchRequestSchema,FrontmatterPatchSuccessSchema,FrontmatterSchemasListSuccessSchema,@@ -114,7 +109,6 @@ import {LEGACY_SKILL_STORE_ROOT,LINKABLE_ASSET_EXTENSIONS,type LifecycleStatus,- LinkGraphSuccessSchema,LinkPreviewRequestSchema,LinkPreviewResponseSchema,type LinksValidationSetting,@@ -237,7 +231,6 @@ import {SkillTargetsPutSuccessSchema,SkillUninstallRequestSchema,SkillUninstallSuccessSchema,- SuggestLinksSuccessSchema,SYSTEM_DOC_NAME,SyncConflictContentSuccessSchema,SyncConflictsSuccessSchema,@@ -249,8 +242,6 @@ import {scanHeadingLine,skillLiveDocName,stripFrontmatter,- TagsForNameSuccessSchema,- TagsListSuccessSchema,TemplateDeleteSuccessSchema,TemplateGetSuccessSchema,TemplateImportRequestSchema,@@ -338,7 +329,6 @@ import {snapshotBlocks,} from './agent-sessions.ts';import { type NormalizedSummary, normalizeSummary } from './agent-write-summary.ts';-import { isAllowedApiOrigin } from './api-origin.ts';import { collectReferencedAssets } from './asset-references.ts';import { collabUrlFromRequestHeaders } from './collab-bootstrap-url.ts';import { createCommentApi } from './comments/comment-api.ts';@@ -379,7 +369,7 @@ import {toContentDivergenceWarning,} from './content-divergence-gate.ts';import { recordContributor } from './contributor-tracker.ts';-import { deriveDetection, embedProbeRing, recordEmbedProbe } from './embed-probe.ts';+import { deriveDetection, embedProbeRing } from './embed-probe.ts';import {FileEmbeddingsBackend,probeEmbeddingEndpoint,@@ -525,15 +515,6 @@ function bundleSelfIdentifiesAsPack(dir: string): boolean {export { extractPageTitle } from './page-identity.ts';import type { SkillHostId } from '@inkeep/open-knowledge-core/skills-catalog';-import { context, propagation, SpanKind, SpanStatusCode } from '@opentelemetry/api';-import {- ATTR_HTTP_REQUEST_METHOD,- ATTR_HTTP_RESPONSE_STATUS_CODE,- ATTR_HTTP_ROUTE,- ATTR_URL_PATH,- ATTR_URL_SCHEME,- ATTR_USER_AGENT_ORIGINAL,-} from '@opentelemetry/semantic-conventions';import simpleGit from 'simple-git';import { parseAgentBodyFields, resolveAgentType, validateAgentId } from './agent-id.ts';import {@@ -566,7 +547,6 @@ import { safeContentPath } from './content-path.ts';import {type DerivedDocumentIndexApiPort,type DerivedDocumentIndexMutation,- type DerivedGraphNode,isDerivedDocumentIndexClosedError,isDerivedOrphanMode,} from './derived-document-index.ts';@@ -620,6 +600,7 @@ import {import { CHECKOUT_HANDLER_TAG, runCheckoutFlow } from './git-checkout.ts';import { withParentLock } from './git-handle.ts';import { writeGitIdentity } from './git-identity.ts';+import { type ApiRouteTable, createApiRequestPipeline } from './http/api-pipeline.ts';import { catchErrors } from './http/catch-errors.ts';import {createStreamingErrorWriter,@@ -627,13 +608,10 @@ import {type HttpErrorStatus,} from './http/error-response.ts';import { errnoCode, parseQuery } from './http/handler-utils.ts';+import { assertSingleRouterOwnership, type NativeApiHandle } from './http/http-app.ts';+import { createLinkGraphRoutes } from './http/link-graph-routes.ts';import { methodRouter } from './http/method-router.ts';-import {- getRequestId,- REQUEST_ID_HEADER,- rememberRequestId,- resolveRequestId,-} from './http/request-id.ts';+import { getRequestId } from './http/request-id.ts';import { validateBody, withValidation } from './http/request-validation.ts';import { successResponse } from './http/success-response.ts';import {@@ -749,28 +727,14 @@ import { restoreSkillVersion } from './skill-restore.ts';import { mutateSkillsLock, readSkillsLockFile } from './skills-lock-store.ts';import { createSkillsShHandlers } from './skills-sh-handlers.ts';import { reportSkillInstall } from './skills-sh-install-report.ts';-import { SuggestLinksTargetNotFoundError, suggestLinks } from './suggest-links.ts';import type { SyncEngine } from './sync-engine.ts';-import { getMeter, getTracer, withSpan, withSpanSync } from './telemetry.ts';+import { getMeter, withSpan, withSpanSync } from './telemetry.ts';import { getDocumentHistory, getFolderTimeline } from './timeline-query.ts';import { recordTimelineCoalesced } from './timeline-telemetry.ts';-// Cache the HTTP duration histogram at module scope — lazy-init at first use-// so the meter is a real meter (post-`initTelemetry`), not the pre-init no-op.-// Recreating the histogram every request allocates + registers a fresh-// instrument on every hit.-let _httpDurationHist: ReturnType<ReturnType<typeof getMeter>['createHistogram']> | null = null;--function httpDurationHist(): ReturnType<ReturnType<typeof getMeter>['createHistogram']> {- _httpDurationHist ||= getMeter().createHistogram('http.server.request.duration', {- description: 'HTTP server request duration in seconds',- unit: 's',- });- return _httpDurationHist;-}-// Lazy-init so the counter registers against a real meter post-initTelemetry-// (not the pre-init no-op). Matches the httpDurationHist pattern.+// (not the pre-init no-op). Matches the httpDurationHist pattern in+// http/api-pipeline.ts.let _hintEmittedCounter: ReturnType<ReturnType<typeof getMeter>['createCounter']> | null = null;function hintEmittedCounter(): ReturnType<ReturnType<typeof getMeter>['createCounter']> {_hintEmittedCounter ||= getMeter().createCounter('ok.preview_attach.hint_emitted', {@@ -2829,7 +2793,9 @@ export interface CommentDocHooks {deleted: (docName: string) => void;}-export function createApiExtension(options: ApiExtensionOptions): Extension {+export function createApiExtension(+ options: ApiExtensionOptions,+): Extension & { nativeApi: NativeApiHandle } {const { durabilityState, remotePublicHost } = options;// Every local-op call site in this factory inherits the remote-origin// widening through this shadow — one choke point, zero per-site churn.@@ -7140,57 +7106,6 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {{ handler: 'document-list', method: 'GET', skipBodyParse: true },);- const handleBacklinks = withValidation(- EmptyRequestSchema,- async (req, res) => {- if (!derivedDocumentIndex) {- errorResponse(- res,- 503,- 'urn:ok:error:backlink-index-not-configured',- 'Backlink index is not configured.',- { handler: 'backlinks' },- );- return;- }- try {- const url = new URL(req.url ?? '', 'http://localhost');- const docName = url.searchParams.get('docName');- if (!docName) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing docName parameter.', {- handler: 'backlinks',- });- return;- }- if (!isSafeDocName(docName)) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {- handler: 'backlinks',- });- return;- }- const backlinks = (await derivedDocumentIndex.getBacklinks(docName)).map((entry) => ({- source: entry.source,- anchor: entry.anchor,- title: readPageTitleForDocName(entry.source),- snippet: entry.snippet,- }));- successResponse(- res,- 200,- BacklinksSuccessSchema,- { docName, backlinks },- { handler: 'backlinks' },- );- } catch (e) {- respondToDerivedIndexQueryFailure(res, e, {- handler: 'backlinks',- failureTitle: 'Failed to read backlinks.',- });- }- },- { handler: 'backlinks', method: 'GET', skipBodyParse: true },- );-/*** Read-only cross-harness installed-skill enumeration. `GET /api/skills/installed`* returns `{ skills, packs }` — every skill OK can see across all harness@@ -7244,57 +7159,6 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {{ handler: 'skills-installed', method: 'GET', skipBodyParse: true },);- /**- * Bulk backlink-count lookup. `GET /api/backlink-counts?docNames=a,b,c`- * returns `{ counts: { a: 3, b: 0, c: 2 } }`. Serves listing UIs- * (exec ls/grep/find slim enrichment) that need connection density per file- * without N-amplifying the single-doc `/api/backlinks` endpoint.- * docNames failing `isSafeDocName` are silently dropped from `counts`.- */- const handleBacklinkCounts = withValidation(- EmptyRequestSchema,- async (req, res) => {- if (!derivedDocumentIndex) {- errorResponse(- res,- 503,- 'urn:ok:error:backlink-index-not-configured',- 'Backlink index is not configured.',- { handler: 'backlink-counts' },- );- return;- }- try {- const url = new URL(req.url ?? '', 'http://localhost');- const raw = url.searchParams.get('docNames');- if (!raw) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing docNames parameter.', {- handler: 'backlink-counts',- });- return;- }- const docNames = raw- .split(',')- .map((docName) => docName.trim())- .filter((docName) => docName && isSafeDocName(docName));- const counts = await derivedDocumentIndex.getBacklinkCounts(docNames);- successResponse(- res,- 200,- BacklinkCountsSuccessSchema,- { counts },- { handler: 'backlink-counts' },- );- } catch (e) {- respondToDerivedIndexQueryFailure(res, e, {- handler: 'backlink-counts',- failureTitle: 'Failed to read backlink counts.',- });- }- },- { handler: 'backlink-counts', method: 'GET', skipBodyParse: true },- );-/*** Bulk unresolved-comment-count lookup, the read-side counterpart to* `/api/backlink-counts`. `GET /api/comment-counts?docNames=a,b,c` returns@@ -7364,169 +7228,6 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {{ handler: 'comment-counts', method: 'GET', skipBodyParse: true },);- const handleForwardLinks = withValidation(- EmptyRequestSchema,- async (req, res) => {- if (!derivedDocumentIndex) {- errorResponse(- res,- 503,- 'urn:ok:error:backlink-index-not-configured',- 'Backlink index is not configured.',- { handler: 'forward-links' },- );- return;- }- try {- const url = new URL(req.url ?? '', 'http://localhost');- const docName = url.searchParams.get('docName');- if (!docName) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing docName parameter.', {- handler: 'forward-links',- });- return;- }- if (!isSafeDocName(docName)) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {- handler: 'forward-links',- });- return;- }- const admitted = await collectAdmittedDocNames();- successResponse(- res,- 200,- ForwardLinksSuccessSchema,- {- docName,- forwardLinks: (await derivedDocumentIndex.getForwardLinkEntries(docName)).map(- (entry) =>- entry.kind === 'doc'- ? {- kind: 'doc' as const,- docName: entry.target,- anchor: entry.anchor,- title: readPageTitleForLinkedDocName(entry.target, admitted),- snippet: entry.snippet,- }- : {- kind: 'external' as const,- url: entry.url,- title: entry.label ?? entry.url,- snippet: entry.snippet,- },- ),- },- { handler: 'forward-links' },- );- } catch (e) {- respondToDerivedIndexQueryFailure(res, e, {- handler: 'forward-links',- failureTitle: 'Failed to read forward links.',- });- }- },- { handler: 'forward-links', method: 'GET', skipBodyParse: true },- );-- const handleLinkGraph = withValidation(- EmptyRequestSchema,- async (req, res) => {- if (!derivedDocumentIndex) {- errorResponse(- res,- 503,- 'urn:ok:error:backlink-index-not-configured',- 'Backlink index is not configured.',- { handler: 'link-graph' },- );- return;- }- try {- const url = new URL(req.url ?? '', 'http://localhost');- const docName = url.searchParams.get('docName');- if (docName && !isSafeDocName(docName)) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {- handler: 'link-graph',- });- return;- }-- const rawDegrees = url.searchParams.get('degrees');- if (rawDegrees && !docName) {- errorResponse(- res,- 400,- 'urn:ok:error:invalid-request',- 'docName is required when degrees is provided.',- { handler: 'link-graph' },- );- return;- }-- let nodes: DerivedGraphNode[];- let links: Array<{ source: string; target: string }>;-- if (rawDegrees && docName) {- const degrees = Number.parseInt(rawDegrees, 10);- if (!Number.isFinite(degrees) || degrees < 0) {- errorResponse(- res,- 400,- 'urn:ok:error:invalid-request',- 'degrees must be a non-negative integer.',- { handler: 'link-graph' },- );- return;- }-- ({ nodes, links } = await derivedDocumentIndex.getLinkGraphNeighborhood(- docName,- degrees,- ));- } else {- ({ nodes, links } = await derivedDocumentIndex.getLinkGraph());- }-- const admitted = await collectAdmittedDocNames();- const enrichedNodes = nodes.map((node) => {- if (node.kind === 'doc') {- const meta = readFrontmatterMetadataForLinkedDocName(node.docName, admitted);- return {- id: node.id,- kind: 'doc' as const,- docName: node.docName,- anchor: node.anchor ?? null,- label: readPageTitleForLinkedDocName(node.docName, admitted),- cluster: meta.cluster ?? null,- category: meta.category ?? null,- tags: meta.tags ?? null,- };- }- return {- id: node.id,- kind: 'external' as const,- url: node.url,- label: node.label ?? node.url,- };- });- successResponse(- res,- 200,- LinkGraphSuccessSchema,- { nodes: enrichedNodes, links },- { handler: 'link-graph' },- );- } catch (e) {- respondToDerivedIndexQueryFailure(res, e, {- handler: 'link-graph',- failureTitle: 'Failed to read link graph.',- });- }- },- { handler: 'link-graph', method: 'GET', skipBodyParse: true },- );-const handleOrphans = withValidation(EmptyRequestSchema,async (req, res) => {@@ -7606,63 +7307,6 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {{ handler: 'hubs', method: 'GET', skipBodyParse: true },);- const handleDeadLinks = withValidation(- EmptyRequestSchema,- async (req, res) => {- if (!derivedDocumentIndex) {- errorResponse(- res,- 503,- 'urn:ok:error:backlink-index-not-configured',- 'Backlink index is not configured.',- { handler: 'dead-links' },- );- return;- }- try {- const url = new URL(req.url ?? '', 'http://localhost');- const sourceDocNames = url.searchParams.getAll('sourceDocName');- if (sourceDocNames.some((docName) => docName.length === 0 || !isSafeDocName(docName))) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid sourceDocName.', {- handler: 'dead-links',- });- return;- }-- const sourceDocNameFilter = sourceDocNames.length- ? [...new Set(sourceDocNames.map((docName) => resolveAlias(docName)))]- : undefined;- const deadLinks = await derivedDocumentIndex.getDeadLinks(- await collectAdmittedDocNames(),- sourceDocNameFilter,- );-- successResponse(- res,- 200,- DeadLinksSuccessSchema,- {- deadLinks: deadLinks.map((entry) => ({- target: entry.target,- sources: entry.sources.map((sourceEntry) => ({- source: sourceEntry.source,- title: readPageTitleForDocName(sourceEntry.source),- snippet: sourceEntry.snippet,- })),- })),- },- { handler: 'dead-links' },- );- } catch (e) {- respondToDerivedIndexQueryFailure(res, e, {- handler: 'dead-links',- failureTitle: 'Failed to read dead links.',- });- }- },- { handler: 'dead-links', method: 'GET', skipBodyParse: true },- );-const handleAgentPatch = withValidation(AgentPatchRequestSchema,async (_req, res, body) => {@@ -11320,58 +10964,6 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {{ handler: 'pages', method: 'GET', skipBodyParse: true },);- const handleSuggestLinks = withValidation(- EmptyRequestSchema,- async (req, res) => {- try {- const url = new URL(req.url ?? '', 'http://localhost');- const docName = url.searchParams.get('docName');- if (!docName) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing docName parameter.', {- handler: 'suggest-links',- });- return;- }- if (!isSafeDocName(docName)) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {- handler: 'suggest-links',- });- return;- }- if (isSystemDoc(docName) || isConfigDoc(docName)) {- errorResponse(- res,- 400,- 'urn:ok:error:reserved-doc-name',- `'${docName}' is a reserved document name.`,- { handler: 'suggest-links' },- );- return;- }-- const result = await suggestLinks({- hocuspocus,- fileIndex: getFileIndex(),- docName,- });- successResponse(res, 200, SuggestLinksSuccessSchema, result, { handler: 'suggest-links' });- } catch (error) {- if (error instanceof SuggestLinksTargetNotFoundError) {- errorResponse(res, 404, 'urn:ok:error:doc-not-found', 'Page not found.', {- handler: 'suggest-links',- cause: error,- });- return;- }- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to suggest links.', {- handler: 'suggest-links',- cause: error,- });- }- },- { handler: 'suggest-links', method: 'GET', skipBodyParse: true },- );-async function handleUploadAsset(req: IncomingMessage, res: ServerResponse): Promise<void> {if (req.method !== 'POST') {errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {@@ -13853,95 +13445,6 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {}}- const handleTagsList = withValidation(- EmptyRequestSchema,- async (_req, res) => {- if (!derivedDocumentIndex) {- errorResponse(- res,- 503,- 'urn:ok:error:tag-index-not-configured',- 'Tag index not configured.',- { handler: 'tags-list' },- );- return;- }- try {- const tags = await derivedDocumentIndex.getAllTags();- successResponse(res, 200, TagsListSuccessSchema, { tags }, { handler: 'tags-list' });- } catch (e) {- respondToDerivedIndexQueryFailure(res, e, {- handler: 'tags-list',- failureTitle: 'Failed to read tags.',- });- }- },- { handler: 'tags-list', method: 'GET', skipBodyParse: true },- );-- async function handleTagsForName(- req: IncomingMessage,- res: ServerResponse,- rawName: string,- ): Promise<void> {- if (req.method !== 'GET') {- errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {- handler: 'tags-for-name',- extraHeaders: { Allow: 'GET' },- });- return;- }- if (!derivedDocumentIndex) {- errorResponse(- res,- 503,- 'urn:ok:error:tag-index-not-configured',- 'Tag index not configured.',- { handler: 'tags-for-name' },- );- return;- }- let name: string;- try {- name = decodeURIComponent(rawName);- } catch {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid tag name encoding.', {- handler: 'tags-for-name',- });- return;- }- if (!name) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing tag name.', {- handler: 'tags-for-name',- });- return;- }- try {- const docs = (await derivedDocumentIndex.getDocsForTagWithMatches(name)).map(- ({ docName, matchingTags }) => ({- docName,- title: readPageTitleForDocName(docName),- matchingTags,- snippet: null,- }),- );- successResponse(- res,- 200,- TagsForNameSuccessSchema,- { name, docs },- {- handler: 'tags-for-name',- },- );- } catch (e) {- respondToDerivedIndexQueryFailure(res, e, {- handler: 'tags-for-name',- failureTitle: 'Failed to read tag membership.',- });- }- }-function validateFolderRel(raw: string,res: ServerResponse,@@ -22892,16 +22395,10 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {'/api/asset-text': handleAssetText,'/api/document': handleDocumentRead,'/api/documents': handleDocumentList,- '/api/backlinks': handleBacklinks,- '/api/backlink-counts': handleBacklinkCounts,'/api/comment-counts': handleCommentCounts,'/api/link-preview': handleLinkPreview,- '/api/forward-links': handleForwardLinks,- '/api/link-graph': handleLinkGraph,- '/api/dead-links': handleDeadLinks,'/api/orphans': handleOrphans,'/api/hubs': handleHubs,- '/api/tags': handleTagsList,'/api/pages': handlePages,'/api/folder-config': handleFolderConfig,'/api/template': handleTemplate,@@ -22940,7 +22437,6 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {'/api/lint/audit': handleLintAudit,'/api/lint/fix': handleLintFix,'/api/audit': handleAudit,- '/api/suggest-links': handleSuggestLinks,'/api/page-headings': handlePageHeadings,'/api/create-page': handleCreatePage,'/api/create-folder': handleCreateFolder,@@ -23081,353 +22577,79 @@ export function createApiExtension(options: ApiExtensionOptions): Extension {// by default.const STATE_MUTATING_PREFIXES: ReadonlyArray<string> = ['/api/local-op/'];- return {- priority: 100, // Higher priority — API routes run before static file serving- async onRequest({ request, response }: { request: IncomingMessage; response: ServerResponse }) {- const url = request.url?.split('?')[0];- if (!url) return;-- // Per-request client-context observation for embed-detection spikes.- // Pushed into a bounded in-process ring buffer drained by- // /api/__embed-detect. Assumes loopback-only deployment — the consumer- // endpoint enforces this. Multi-valued headers (rare) collapse to the- // joined string Node provides by default for the headers we capture.- const headerString = (name: string): string | undefined => {- const value = request.headers[name];- if (value === undefined) return undefined;- return Array.isArray(value) ? value.join(', ') : value;- };- recordEmbedProbe({- ts: Date.now(),- url,- method: request.method ?? '',- ua: headerString('user-agent'),- origin: headerString('origin'),- referer: headerString('referer'),- host: headerString('host'),- remote: request.socket?.remoteAddress,- secChUa: headerString('sec-ch-ua'),- secChUaMobile: headerString('sec-ch-ua-mobile'),- secChUaPlatform: headerString('sec-ch-ua-platform'),- secFetchSite: headerString('sec-fetch-site'),- secFetchDest: headerString('sec-fetch-dest'),- secFetchMode: headerString('sec-fetch-mode'),- secFetchUser: headerString('sec-fetch-user'),- });-- const method = request.method ?? 'GET';- // Normalize route for low-cardinality labels (metric labels, span- // attributes, and the access log below). `:id` placeholders replace- // dynamic segments; anything else collapses to the URL prefix.- let routeTemplate = url;- if (url.startsWith('/api/history/')) routeTemplate = '/api/history/:sha';- else if (url.startsWith('/api/tags/')) routeTemplate = '/api/tags/:name';- else if (!routes[url]) routeTemplate = '/api/*';-- // Request identity + access log for the /api/* surface. Slots BEFORE the- // origin/loopback/host gates (without touching their order) so even- // gate-rejected responses carry the `x-request-id` echo and produce an- // access-log line. The `typeof` guards mirror the CORS block below —- // unit-test doubles stub only `writeHead` + `end`.- const requestId = url.startsWith('/api/') ? resolveRequestId(request) : undefined;- if (requestId !== undefined) {- rememberRequestId(request, requestId);- if (typeof response.setHeader === 'function') {- response.setHeader(REQUEST_ID_HEADER, requestId);- }- if (typeof response.once === 'function') {- const accessStarted = Date.now();- let accessLogged = false;- // One line per request on whichever of finish/close fires first:- // 'finish' is the fully-flushed response (including long-lived- // NDJSON streams, logged at stream end); 'close' catches aborted- // sockets (client disconnect, timeout destroy) that never finish.- // Route TEMPLATE, never the raw path — cardinality discipline for- // log aggregators matches the metric-label STOP rule. Byte counts- // are omitted: Node exposes no cheap per-response counter under- // chunked encoding (socket.bytesWritten is per-connection).- const emitAccessLog = () => {- if (accessLogged) return;- accessLogged = true;- log.info(- {- event: 'api.access',- requestId,- method,- route: routeTemplate,- status: response.statusCode,- durationMs: Date.now() - accessStarted,- ...(response.writableFinished ? {} : { aborted: true }),- },- `${method} ${routeTemplate} ${response.statusCode}`,- );- };- response.once('finish', emitAccessLog);- response.once('close', emitAccessLog);- }- }-- // Origin-allowlist CORS for /api/*. Only loopback origins are accepted:- // - No Origin header (same-origin browser tab, curl, CLI): passes through.- // - Origin "null" (Electron packaged renderer, file:// per Fetch spec §4.3): allowed.- // - http(s)://localhost[:port] / 127.x.x.x[:port] / [::1][:port]: allowed.- // - Any other Origin: 403 — closes the CSRF door on unauthenticated mutating- // routes (/api/agent-write-md, /api/rollback, /api/manage/delete, etc.)- // without breaking the Electron renderer or local Vite dev servers.- //- // When an allowed Origin is present, it is reflected verbatim in ACAO (not- // `*`) so the browser's preflight check passes while non-loopback origins are- // still refused by the gate above. `Vary: Origin` prevents cache poisoning.- //- // Setting via `setHeader` (not `writeHead`) so handler responses that call- // `writeHead(status, { ... })` inherit these headers. The typeof guard handles- // unit tests that stub only `writeHead` + `end`.- if (url.startsWith('/api/')) {- const origin = request.headers.origin;- if (origin !== undefined && !isAllowedApiOrigin(origin, remotePublicHost)) {- // RFC 9457 problem+json. Tag the handler as `api-origin-gate` so- // the `ok.api.error.count` counter distinguishes onRequest-level- // CSRF rejections from per-handler emits. The cross-origin browser- // can't read the body anyway (CORS strips it) but consistent wire- // shape lets server-to-server callers + tests parse uniformly.- errorResponse(response, 403, 'urn:ok:error:invalid-origin', 'Origin not allowed.', {- handler: 'api-origin-gate',- });- return;- }- if (typeof response.setHeader === 'function') {- if (origin !== undefined) {- response.setHeader('Access-Control-Allow-Origin', origin);- response.setHeader('Vary', 'Origin');- }- response.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');- // Content-Type/Authorization: standard request headers. traceparent/- // tracestate/baggage: OTel W3C trace-context propagation from the- // browser SDK. x-ok-client-*: the client→version metadata the renderer- // stamps on every /api/* request (clientVersionHeaders) — omitting- // these fails the preflight for the cross-origin renderer (dev Vite- // origin / file:// packaged) before the real request fires.- response.setHeader(- 'Access-Control-Allow-Headers',- `Content-Type, Authorization, traceparent, tracestate, baggage, ${REQUEST_ID_HEADER}, ${CLIENT_VERSION_HEADER.protocol}, ${CLIENT_VERSION_HEADER.runtime}, ${CLIENT_VERSION_HEADER.kind}`,- );- // Let cross-origin renderer JS read the correlation ID echo — CORS- // hides non-safelisted response headers by default.- response.setHeader('Access-Control-Expose-Headers', REQUEST_ID_HEADER);- }- // OPTIONS preflight — short-circuit with 204 + the headers above.- if (request.method === 'OPTIONS') {- response.writeHead(204);- response.end();- return;- }+ // The legacy route table's view for the shared /api/* admission pipeline+ // (`http/api-pipeline.ts` — the same pipeline the native Hono routes run).+ // `resolve` never declines an /api/* URL: unmatched paths resolve to the+ // bounded `/api/*` template with no dispatch so the pipeline's explicit+ // RFC 9457 404 owns the response and the dispatch surface stays closed.+ const apiRouteTable: ApiRouteTable = {+ resolve(url) {+ const handler = routes[url];+ if (handler) {+ return { template: url, dispatch: (req, res) => handler(req, res) };}-- // DNS-rebinding defense for state-mutating endpoints. The- // `isLoopbackAddress` TCP-peer check and `isAllowedWorkspaceHostHeader`- // Host-header check together block the standard rebinding pattern- // (attacker-owned hostname whose DNS resolves to 127.0.0.1 after an- // initial attacker-serves-JS response — the TCP peer is loopback,- // but the Host header names the attacker domain). The same mitigation- // already gates `/api/workspace`; without it, a rebinding page could- // POST /api/upload + /api/agent-write, mutating the local vault.- //- // Test-harness note: Node's production socket always has- // `remoteAddress` set by the kernel; the only path that reaches- // this check without a socket is a mocked `IncomingMessage` built- // from `Readable.from(...)`. Those mocks bypass the HTTP listener- // entirely and can't be reached by a real remote attacker, so a- // missing socket is treated as test-context and skips the check.- // The Host-header gate still fires (tests set `host: 'localhost'`),- // so the protection remains meaningful for any production path.- if (MUTATING_ROUTES.has(url) || STATE_MUTATING_PREFIXES.some((p) => url.startsWith(p))) {- const peerAddress = request.socket?.remoteAddress;- if (peerAddress !== undefined && !isLoopbackAddress(peerAddress)) {- errorResponse(response, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {- handler: 'api-mutating-gate',- });- return;- }- if (!isAllowedWorkspaceHostHeader(request.headers.host)) {- errorResponse(- response,- 403,- 'urn:ok:error:host-not-allowed',- 'Host header not allowed.',- { handler: 'api-mutating-gate' },- );- return;- }- }-- // No-project ephemeral single-file mode (`ok <file>`) sets contentDir to- // the opened file's PARENT — often a user-data dir (~/Downloads,- // ~/Documents). Several read routes (`/api/asset`, `/api/asset-text`,- // `/api/document`) return bytes under contentDir bounded only by- // `isWithinContentDir`, NOT by the single-file content scope (which is- // enforced at the indexing/listing layer, not the byte-read path). So- // without a host gate a DNS-rebound page could exfiltrate sibling files.- // Apply the same loopback + workspace-host check the mutating gate uses to- // EVERY `/api/*` request in ephemeral mode — one choke point, so future- // read routes inherit it rather than each needing its own gate. Project /- // desktop modes (`ephemeral` falsy) keep their prior origin-only posture- // for reads (the user chose the served root there); this mirrors the- // ephemeral-scoped content-asset gate in `mcp-mount.ts`, which covers the- // non-`/api/` static-serve path.- if (ephemeral && url.startsWith('/api/')) {- const peerAddress = request.socket?.remoteAddress;- if (peerAddress !== undefined && !isLoopbackAddress(peerAddress)) {- errorResponse(response, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {- handler: 'api-ephemeral-gate',- });- return;- }- if (!isAllowedWorkspaceHostHeader(request.headers.host)) {- errorResponse(- response,- 403,- 'urn:ok:error:host-not-allowed',- 'Host header not allowed.',- {- handler: 'api-ephemeral-gate',- },- );- return;- }+ if (url.startsWith('/api/history/')) {+ const encodedSha = url.slice('/api/history/'.length);+ return {+ template: '/api/history/:sha',+ // Decode inside dispatch so a malformed encoding surfaces as the+ // dispatch span's typed 500, not a resolve-time throw.+ dispatch: encodedSha+ ? async (req, res) => {+ await handleHistoryVersion(req, res, decodeURIComponent(encodedSha));+ }+ : undefined,+ };}+ return { template: '/api/*' };+ },+ isMutating: (url) =>+ MUTATING_ROUTES.has(url) || STATE_MUTATING_PREFIXES.some((p) => url.startsWith(p)),+ };- // Only /api/* gets a server span. Non-API routes (static file serving,- // Hocuspocus's own paths) fall through silently. (Route dispatch- // happens inside the OTel active-span block below.)- if (!url.startsWith('/api/')) return;-- // Extract incoming trace context (W3C traceparent header) so this server- // span attaches as a child of the browser-initiated trace.- const extractedCtx = propagation.extract(context.active(), request.headers);-- const tracer = getTracer();- const started = Date.now();- await context.with(extractedCtx, () =>- tracer.startActiveSpan(- `HTTP ${method} ${routeTemplate}`,- {- kind: SpanKind.SERVER,- attributes: {- [ATTR_HTTP_REQUEST_METHOD]: method,- [ATTR_HTTP_ROUTE]: routeTemplate,- [ATTR_URL_PATH]: url,- [ATTR_URL_SCHEME]: 'http',- [ATTR_USER_AGENT_ORIGINAL]: request.headers['user-agent'] ?? '',- // Correlation ID (UUID or client-supplied bounded token) — a- // sanctioned span attribute like `ok.error.instance`; the- // cardinality STOP rule governs metric labels, which stay- // request-id-free.- 'ok.request.id': requestId,- },- },- async (span) => {- try {- // Static routes- const handler = routes[url];- let dispatched = false;- if (handler) {- dispatched = true;- await handler(request, response);- } else if (url.startsWith('/api/history/')) {- const sha = decodeURIComponent(url.slice('/api/history/'.length));- if (sha) {- dispatched = true;- await handleHistoryVersion(request, response, sha);- }- } else if (url.startsWith('/api/tags/')) {- const rawName = url.slice('/api/tags/'.length);- if (rawName) {- dispatched = true;- await handleTagsForName(request, response, rawName);- }- }+ const runApiPipeline = createApiRequestPipeline({+ log,+ remotePublicHost,+ ephemeral,+ table: apiRouteTable,+ });- // Defense-in-depth: unmatched `/api/*` routes (typos, removed- // endpoints, empty `/api/rescue/` / `/api/history/` segments)- // would otherwise fall through with no response body, leaving- // Hocuspocus's `onRequest` machinery to either pass through to- // static-file middleware or hang. Emit an explicit RFC 9457 404- // so the dispatch surface is fully closed. Dispatch flag is- // robust against test-mock `ServerResponse` shapes that don't- // simulate `headersSent` (vs checking `response.headersSent`- // directly, which would misfire on mocks after a handler- // successfully wrote 200).- if (!dispatched) {- // `detail` echoes the actual requested URL (no information- // leak — the client sent it). `routeTemplate` is bounded- // to `/api/*` for unmatched routes and used only for- // histogram labels / span attributes upstream — keeping- // the two concerns separate so the wire-detail stays- // actionable for debuggers without coupling to the- // cardinality-bounded telemetry surface.- errorResponse(response, 404, 'urn:ok:error:not-found', 'API endpoint not found.', {- handler: 'api-dispatch',- detail: `No handler for ${method} ${url}`,- });- }+ // The natively-routed link/graph read group (`http/link-graph-routes.ts`).+ // Its paths live in the Hono app only — deliberately absent from `routes`+ // above (a route lives in exactly one router). The handle rides the same+ // shared pipeline with the group's own table, so gate behavior is identical+ // to the legacy dispatch by construction.+ const linkGraphRoutes = createLinkGraphRoutes({+ hocuspocus,+ derivedDocumentIndex,+ getFileIndex,+ isSafeDocName,+ readPageTitleForDocName,+ readPageTitleForLinkedDocName,+ readFrontmatterMetadataForLinkedDocName,+ collectAdmittedDocNames,+ resolveAlias,+ respondToDerivedIndexQueryFailure,+ });+ // "A route lives in exactly one router" — enforced at construction, not+ // just documented; covers every future group aggregated into the native+ // paths. Throw semantics pinned in `http/http-app.test.ts`.+ assertSingleRouterOwnership(linkGraphRoutes.paths, routes);+ const nativeApi: NativeApiHandle = {+ paths: linkGraphRoutes.paths,+ dispatch: createApiRequestPipeline({+ log,+ remotePublicHost,+ ephemeral,+ table: linkGraphRoutes.table,+ }),+ };- const status = response.statusCode;- span.setAttribute(ATTR_HTTP_RESPONSE_STATUS_CODE, status);- if (status >= 500) {- span.setStatus({ code: SpanStatusCode.ERROR, message: `status ${status}` });- }- } catch (err) {- span.recordException(err as Error);- span.setStatus({- code: SpanStatusCode.ERROR,- message: err instanceof Error ? err.message : String(err),- });- // Last-resort RFC 9457 envelope. Per-handler try/catch is the- // primary error boundary, but a synchronous throw before any- // response write would otherwise reach the client as a- // connection reset (or Hocuspocus default error handling) —- // not the typed application/problem+json envelope SDK- // consumers parse. Guard on- // `!headersSent && !writableEnded && !destroyed` so we- // don't double-emit when the inner handler already wrote a- // response or the socket was destroyed mid-handler — same- // three-way guard `createStreamingErrorWriter` uses for- // mid-stream emission. Handler tag is the matched route- // template so telemetry attributes a 5xx surge to the- // failing endpoint.- if (!response.headersSent && !response.writableEnded && !response.destroyed) {- errorResponse(- response,- 500,- 'urn:ok:error:internal-server-error',- 'Internal server error.',- {- handler: routeTemplate,- cause: err,- },- );- }- // Re-throw so Hocuspocus's onRequest extension chain logs the- // exception via its built-in error machinery. The response is- // already ended (either by errorResponse above or by an- // earlier handler write), so Hocuspocus 4.x treats this as a- // post-response observation, not a connection-level failure.- // Verify this assumption holds when bumping Hocuspocus —- // version-specific reaction to throws from onRequest is- // framework-internal behavior.- throw err;- } finally {- span.end();- const durSec = (Date.now() - started) / 1000;- httpDurationHist().record(durSec, {- [ATTR_HTTP_REQUEST_METHOD]: method,- [ATTR_HTTP_ROUTE]: routeTemplate,- [ATTR_HTTP_RESPONSE_STATUS_CODE]: response.statusCode,- });- }- },- ),- );+ return {+ priority: 100, // Higher priority — API routes run before static file serving+ async onRequest({ request, response }: { request: IncomingMessage; response: ServerResponse }) {+ await runApiPipeline(request, response);},+ nativeApi,};}diff --git a/packages/server/src/api-link-graph-composition.test.ts b/packages/server/src/api-link-graph-composition.test.tsnew file mode 100644index 000000000..d4b3964e9--- /dev/null+++ b/packages/server/src/api-link-graph-composition.test.ts@@ -0,0 +1,134 @@+import { mkdtempSync, writeFileSync } from 'node:fs';+import { mkdtemp, rm } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import { resolve } from 'node:path';+import { afterAll, beforeAll, describe, expect, test } from 'vitest';+import type { BootedServer } from './boot.ts';+import { bootCompositionRig, parseProblem, rawRequest } from './composition-rig.test-helper.ts';++/**+ * Characterization: the natively-routed link/graph read group over a REAL+ * socket through the composed `bootServer` stack. These routes left the+ * legacy dispatch registry when they moved to the Hono mount, so a 200 here+ * is proof of native serving — a wiring gap would surface as the legacy+ * dispatch's 404. The admission-gate pins mirror+ * `api-admission-composition.test.ts` on a ported route, closing the exact+ * bypass the native mount exists to prevent.+ */++let tmpRoot: string;+let normal: BootedServer;+let ephemeral: BootedServer;++beforeAll(async () => {+ tmpRoot = await mkdtemp(resolve(tmpdir(), 'ok-linkgraph-native-'));++ const normalDir = mkdtempSync(resolve(tmpRoot, 'normal-'));+ writeFileSync(resolve(normalDir, 'alpha.md'), '# Alpha\n\nLinks to [[beta]].\n', 'utf-8');+ writeFileSync(resolve(normalDir, 'beta.md'), '# Beta\n\nBody.\n', 'utf-8');+ normal = await bootCompositionRig(normalDir);+ await normal.ready;++ const ephemeralDir = mkdtempSync(resolve(tmpRoot, 'ephemeral-'));+ writeFileSync(resolve(ephemeralDir, 'note.md'), '# note\n', 'utf-8');+ ephemeral = await bootCompositionRig(ephemeralDir, {+ ephemeral: true,+ singleDocRelPath: 'note.md',+ });+ await ephemeral.ready;+}, 60_000);++afterAll(async () => {+ await Promise.allSettled([normal?.destroy(), ephemeral?.destroy()]);+ await rm(tmpRoot, { recursive: true, force: true });+});++describe('link/graph group over the composed listener — served natively', () => {+ test('every static route in the group answers (absent from the legacy registry)', async () => {+ for (const path of [+ '/api/backlinks?docName=beta',+ '/api/backlink-counts?docNames=alpha,beta',+ '/api/forward-links?docName=alpha',+ '/api/link-graph',+ '/api/dead-links',+ '/api/tags',+ '/api/suggest-links?docName=alpha',+ ]) {+ const res = await fetch(`http://127.0.0.1:${normal.port}${path}`);+ expect(res.status, path).toBe(200);+ expect(res.headers.get('content-type'), path).toBe('application/json');+ expect(res.headers.get('x-request-id'), path).not.toBeNull();+ }+ });++ test('the parametric tags route answers; the empty tail 404s under the typed envelope', async () => {+ const named = await fetch(`http://127.0.0.1:${normal.port}/api/tags/some-tag`);+ expect(named.status).toBe(200);++ const empty = await fetch(`http://127.0.0.1:${normal.port}/api/tags/`);+ expect(empty.status).toBe(404);+ expect(empty.headers.get('content-type')).toBe('application/problem+json');+ expect(((await empty.json()) as { type?: string }).type).toBe('urn:ok:error:not-found');+ });++ test('method gate holds on the native mount (POST answers 405 + Allow: GET)', async () => {+ const res = await fetch(`http://127.0.0.1:${normal.port}/api/backlinks`, { method: 'POST' });+ expect(res.status).toBe(405);+ expect(res.headers.get('allow')).toBe('GET');+ });++ test('foreign Origin is refused before dispatch on a ported route', async () => {+ const res = await fetch(`http://127.0.0.1:${normal.port}/api/backlinks?docName=beta`, {+ headers: { Origin: 'https://evil.example' },+ });+ expect(res.status).toBe(403);+ const body = (await res.json()) as { type?: string };+ expect(body.type).toBe('urn:ok:error:invalid-origin');+ });++ test('allowed browser Origin gets CORS reflection on a ported route', async () => {+ const res = await fetch(`http://127.0.0.1:${normal.port}/api/backlinks?docName=beta`, {+ headers: { Origin: 'http://localhost:5173' },+ });+ expect(res.status).toBe(200);+ expect(res.headers.get('access-control-allow-origin')).toBe('http://localhost:5173');+ expect(res.headers.get('vary')).toContain('Origin');+ });++ test('OPTIONS preflight answers 204 on a ported route', async () => {+ const res = await fetch(`http://127.0.0.1:${normal.port}/api/backlinks`, {+ method: 'OPTIONS',+ headers: { Origin: 'http://localhost:5173' },+ });+ expect(res.status).toBe(204);+ expect(res.headers.get('access-control-allow-methods')).toBe('GET, POST, PUT, DELETE, OPTIONS');+ });++ test('any forwarding header trips the proxied-request refusal on a ported route', async () => {+ const res = await rawRequest(normal.port, '/api/backlinks?docName=beta', {+ headers: { 'X-Forwarded-For': '203.0.113.7' },+ });+ expect(res.status).toBe(403);+ const body = parseProblem(res.body);+ expect(body.type).toBe('urn:ok:error:host-not-allowed');+ expect(body.detail ?? body.title).toContain('Proxied request refused');+ });++ test('read posture parity: a ported route ANSWERS under a rebound Host in normal mode', async () => {+ // Same deliberate pin as the legacy-dispatch suite: read-shaped routes+ // are Origin-gated but NOT Host/loopback-gated. When the hosted-auth work+ // flips that posture, this assertion flips in the same PR.+ const res = await rawRequest(normal.port, '/api/backlinks?docName=beta', {+ headers: { Host: 'evil.example' },+ });+ expect(res.status).toBe(200);+ });++ test('ephemeral mode Host-gates the ported reads too', async () => {+ const res = await rawRequest(ephemeral.port, '/api/backlinks?docName=note', {+ headers: { Host: 'evil.example' },+ });+ expect(res.status).toBe(403);+ expect(parseProblem(res.body).type).toBe('urn:ok:error:host-not-allowed');+ });+});diff --git a/packages/server/src/boot.ts b/packages/server/src/boot.tsindex 872ca67e4..204f5f555 100644--- a/packages/server/src/boot.ts+++ b/packages/server/src/boot.ts@@ -918,6 +918,7 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {const mount = mountMcpAndApi({httpServer,hocuspocus,+ nativeApi: serverInstance.nativeApi,mcpHttpHandler,remoteAccess,health: {diff --git a/packages/server/src/frontmatter-telemetry.ts b/packages/server/src/frontmatter-telemetry.tsindex c2fe60936..b1b440b64 100644--- a/packages/server/src/frontmatter-telemetry.ts+++ b/packages/server/src/frontmatter-telemetry.ts@@ -3,7 +3,7 @@** Lazy-init meter so registration runs against a real provider post-* `initTelemetry` (not the pre-init no-op). Same pattern as- * `api-extension.ts:httpDurationHist` and+ * `http/api-pipeline.ts:httpDurationHist` and* `file-watcher.ts:_fileWatcherEventsCounter`. Co-located here so all* edit-surface sites (`applyAgentMarkdownWrite`, `applyExternalChange`,* server-observers Observer B) call into one set of instruments.diff --git a/packages/server/src/health-routes.test.ts b/packages/server/src/health-routes.test.tsindex 94b1f651b..69af9ff96 100644--- a/packages/server/src/health-routes.test.ts+++ b/packages/server/src/health-routes.test.ts@@ -165,6 +165,7 @@ describe('/readyz provider states (mounted harness)', () => {const httpServer = createServer();const mount = mountMcpAndApi({httpServer,+ nativeApi: undefined,hocuspocus: fakeHocuspocus,log: fakeLog as never,...(readiness === undefined@@ -208,6 +209,7 @@ describe('/readyz provider states (mounted harness)', () => {const httpServer = createServer();const mount = mountMcpAndApi({httpServer,+ nativeApi: undefined,hocuspocus: fakeHocuspocus,log: fakeLog as never,health: {diff --git a/packages/server/src/http/api-pipeline.test.ts b/packages/server/src/http/api-pipeline.test.tsnew file mode 100644index 000000000..9fd2a28f8--- /dev/null+++ b/packages/server/src/http/api-pipeline.test.ts@@ -0,0 +1,306 @@+import { createServer } from 'node:http';+import { describe, expect, test } from 'vitest';+import { parseProblem, rawRequest } from '../composition-rig.test-helper.ts';+import { listenOnLoopback } from '../loopback-rig-test-helpers.ts';+import { type ApiRouteTable, createApiRequestPipeline } from './api-pipeline.ts';+import { createHttpApp, type NativeApiHandle } from './http-app.ts';++/**+ * Gate parity for natively-mounted `/api/*` routes. The composition suite+ * (`api-admission-composition.test.ts`) pins the admission gates as the+ * LEGACY dispatch applies them; this suite pins the same wire behavior for+ * routes mounted ABOVE the strangler catch-all through `NativeApiHandle` —+ * the exact bypass the native mount exists to close. A synthetic route table+ * keeps the pins independent of any real route group's handler behavior.+ */++const fakeLog = {+ error: () => {},+ warn: () => {},+ info: () => {},+ debug: () => {},+ child: () => fakeLog,+} as never;++/** The exact preflight header list the legacy dispatch reflects — byte-pinned. */+const EXPECTED_ALLOW_HEADERS =+ 'Content-Type, Authorization, traceparent, tracestate, baggage, x-request-id, x-ok-client-protocol, x-ok-client-runtime, x-ok-client-kind';++interface NativeRig {+ port: number;+ baseUrl: string;+ legacyCalls: string[];+ close: () => Promise<void>;+}++async function bootNativeRig(opts: { ephemeral?: boolean } = {}): Promise<NativeRig> {+ const legacyCalls: string[] = [];+ const table: ApiRouteTable = {+ resolve(pathname) {+ if (pathname === '/api/native-ping' || pathname === '/api/native-mutating') {+ return {+ template: pathname,+ dispatch: async (_req, res) => {+ res.writeHead(200, { 'Content-Type': 'application/json' });+ res.end(JSON.stringify({ pong: true }));+ },+ };+ }+ if (pathname === '/api/native-throw') {+ return {+ template: pathname,+ dispatch: async () => {+ throw new Error('handler boom');+ },+ };+ }+ // Owned prefix with no handler — the pipeline's 404 must close it.+ if (pathname === '/api/native-empty') {+ return { template: '/api/native-empty' };+ }+ return null;+ },+ isMutating: (pathname) => pathname === '/api/native-mutating',+ };+ const nativeApi: NativeApiHandle = {+ paths: [+ '/api/native-ping',+ '/api/native-mutating',+ '/api/native-throw',+ '/api/native-empty',+ // Claimed by the router but declined by the table — must fall through+ // to the legacy dispatch.+ '/api/native-declined',+ ],+ dispatch: createApiRequestPipeline({+ log: fakeLog,+ ephemeral: opts.ephemeral,+ table,+ }),+ };+ const { requestListener } = createHttpApp({+ nativeApi,+ legacyDispatch: (req, res) => {+ legacyCalls.push(req.url ?? '');+ res.writeHead(299, { 'Content-Type': 'text/plain' });+ res.end('legacy');+ },+ log: fakeLog,+ });+ const server = createServer(requestListener);+ const { port, baseUrl } = await listenOnLoopback(server);+ return {+ port,+ baseUrl,+ legacyCalls,+ close: () =>+ new Promise<void>((resolvePromise, reject) => {+ server.close((err) => (err ? reject(err) : resolvePromise()));+ }),+ };+}++describe('natively-mounted /api routes run the shared admission pipeline', () => {+ test('a claimed route is served natively — the legacy dispatch never sees it', async () => {+ const rig = await bootNativeRig();+ try {+ const res = await fetch(`${rig.baseUrl}/api/native-ping`);+ expect(res.status).toBe(200);+ expect(await res.json()).toEqual({ pong: true });+ expect(rig.legacyCalls).toEqual([]);+ } finally {+ await rig.close();+ }+ });++ test('an unclaimed route still flows through the legacy dispatch', async () => {+ const rig = await bootNativeRig();+ try {+ const res = await fetch(`${rig.baseUrl}/api/anything-else`);+ expect(res.status).toBe(299);+ expect(rig.legacyCalls).toEqual(['/api/anything-else']);+ } finally {+ await rig.close();+ }+ });++ test('a claimed path the table declines falls through to the legacy dispatch', async () => {+ const rig = await bootNativeRig();+ try {+ const res = await fetch(`${rig.baseUrl}/api/native-declined`);+ expect(res.status).toBe(299);+ expect(rig.legacyCalls).toEqual(['/api/native-declined']);+ } finally {+ await rig.close();+ }+ });++ test('a dot-segment URL the router normalizes onto a claimed path still gets a response', async () => {+ const rig = await bootNativeRig();+ try {+ // Hono matches `/api/./native-ping` against the claimed path (the+ // adapter normalizes dot segments), but the pipeline resolves the RAW+ // req.url and declines it — the fall-through must hand the request to+ // the legacy dispatch rather than leaving it unanswered.+ const res = await rawRequest(rig.port, '/api/./native-ping', {});+ expect(res.status).toBe(299);+ expect(rig.legacyCalls).toEqual(['/api/./native-ping']);+ } finally {+ await rig.close();+ }+ });++ test('responses carry the x-request-id echo, honoring a well-formed inbound ID', async () => {+ const rig = await bootNativeRig();+ try {+ const minted = await fetch(`${rig.baseUrl}/api/native-ping`);+ expect(minted.headers.get('x-request-id')).toMatch(/^[A-Za-z0-9._-]{1,128}$/);++ const echoed = await fetch(`${rig.baseUrl}/api/native-ping`, {+ headers: { 'x-request-id': 'caller-chosen.id-42' },+ });+ expect(echoed.headers.get('x-request-id')).toBe('caller-chosen.id-42');+ } finally {+ await rig.close();+ }+ });++ test('a foreign Origin is refused before dispatch with the legacy problem shape', async () => {+ const rig = await bootNativeRig();+ try {+ const res = await fetch(`${rig.baseUrl}/api/native-ping`, {+ headers: { Origin: 'https://evil.example' },+ });+ expect(res.status).toBe(403);+ expect(res.headers.get('content-type')).toBe('application/problem+json');+ const body = (await res.json()) as { type?: string; title?: string };+ expect(body.type).toBe('urn:ok:error:invalid-origin');+ expect(body.title).toBe('Origin not allowed.');+ // The rejection still carries the request-id echo (identity slots+ // BEFORE the gates).+ expect(res.headers.get('x-request-id')).not.toBeNull();+ } finally {+ await rig.close();+ }+ });++ test('an allowed browser Origin gets verbatim CORS reflection with the exact header list', async () => {+ const rig = await bootNativeRig();+ try {+ const res = await fetch(`${rig.baseUrl}/api/native-ping`, {+ headers: { Origin: 'http://localhost:5173' },+ });+ expect(res.status).toBe(200);+ expect(res.headers.get('access-control-allow-origin')).toBe('http://localhost:5173');+ expect(res.headers.get('vary')).toContain('Origin');+ expect(res.headers.get('access-control-allow-methods')).toBe(+ 'GET, POST, PUT, DELETE, OPTIONS',+ );+ expect(res.headers.get('access-control-allow-headers')).toBe(EXPECTED_ALLOW_HEADERS);+ expect(res.headers.get('access-control-expose-headers')).toBe('x-request-id');+ } finally {+ await rig.close();+ }+ });++ test('OPTIONS preflight answers 204 with the CORS headers', async () => {+ const rig = await bootNativeRig();+ try {+ const res = await fetch(`${rig.baseUrl}/api/native-ping`, {+ method: 'OPTIONS',+ headers: { Origin: 'http://localhost:5173' },+ });+ expect(res.status).toBe(204);+ expect(res.headers.get('access-control-allow-methods')).toBe(+ 'GET, POST, PUT, DELETE, OPTIONS',+ );+ } finally {+ await rig.close();+ }+ });++ test('any forwarding header trips the proxied-request refusal on a native route', async () => {+ const rig = await bootNativeRig();+ try {+ const res = await rawRequest(rig.port, '/api/native-ping', {+ headers: { 'X-Forwarded-For': '203.0.113.7' },+ });+ expect(res.status).toBe(403);+ const body = parseProblem(res.body);+ expect(body.type).toBe('urn:ok:error:host-not-allowed');+ expect(body.detail ?? body.title).toContain('Proxied request refused');+ } finally {+ await rig.close();+ }+ });++ test('a mutating native route under a rebound Host is refused; a read route answers', async () => {+ const rig = await bootNativeRig();+ try {+ const refused = await rawRequest(rig.port, '/api/native-mutating', {+ headers: { Host: 'evil.example' },+ });+ expect(refused.status).toBe(403);+ expect(parseProblem(refused.body).type).toBe('urn:ok:error:host-not-allowed');++ // Read posture parity: Origin-gated but NOT Host-gated in normal mode.+ const read = await rawRequest(rig.port, '/api/native-ping', {+ headers: { Host: 'evil.example' },+ });+ expect(read.status).toBe(200);++ const allowed = await rawRequest(rig.port, '/api/native-mutating', {+ headers: { Host: 'localhost' },+ });+ expect(allowed.status).toBe(200);+ } finally {+ await rig.close();+ }+ });++ test('ephemeral mode Host-gates EVERY native /api route, including reads', async () => {+ const rig = await bootNativeRig({ ephemeral: true });+ try {+ const refused = await rawRequest(rig.port, '/api/native-ping', {+ headers: { Host: 'evil.example' },+ });+ expect(refused.status).toBe(403);+ expect(parseProblem(refused.body).type).toBe('urn:ok:error:host-not-allowed');++ const allowed = await rawRequest(rig.port, '/api/native-ping', {+ headers: { Host: 'localhost' },+ });+ expect(allowed.status).toBe(200);+ } finally {+ await rig.close();+ }+ });++ test('an owned URL with no handler gets the explicit RFC 9457 404', async () => {+ const rig = await bootNativeRig();+ try {+ const res = await fetch(`${rig.baseUrl}/api/native-empty`);+ expect(res.status).toBe(404);+ expect(res.headers.get('content-type')).toBe('application/problem+json');+ const body = (await res.json()) as { type?: string; title?: string };+ expect(body.type).toBe('urn:ok:error:not-found');+ expect(body.title).toBe('API endpoint not found.');+ expect(rig.legacyCalls).toEqual([]);+ } finally {+ await rig.close();+ }+ });++ test('a throwing handler surfaces as the typed 500 envelope, not a reset', async () => {+ const rig = await bootNativeRig();+ try {+ const res = await fetch(`${rig.baseUrl}/api/native-throw`);+ expect(res.status).toBe(500);+ expect(res.headers.get('content-type')).toBe('application/problem+json');+ const body = (await res.json()) as { type?: string };+ expect(body.type).toBe('urn:ok:error:internal-server-error');+ } finally {+ await rig.close();+ }+ });+});diff --git a/packages/server/src/http/api-pipeline.ts b/packages/server/src/http/api-pipeline.tsnew file mode 100644index 000000000..84d67b8fc--- /dev/null+++ b/packages/server/src/http/api-pipeline.ts@@ -0,0 +1,453 @@+/**+ * The `/api/*` admission pipeline — request identity, CORS, DNS-rebinding+ * gates, and the OTel dispatch span — shared by BOTH routers during the+ * strangler migration.+ *+ * The pipeline used to live inline in `api-extension.ts`'s `onRequest` hook.+ * Native routes mounted on the canonical Hono app sit ABOVE the strangler+ * catch-all and therefore bypass that hook entirely — safe for the health+ * probes, a security regression for `/api/*`. Extracting the pipeline and+ * dispatching both routers through it makes byte parity structural: one+ * implementation, two route tables. When the legacy dispatch handles nothing,+ * its table is deleted and the pipeline keeps running for the native one.+ *+ * The gate ORDER is load-bearing and mirrors the historical hook exactly:+ *+ * 1. embed-probe observation (ring buffer drained by `/api/__embed-detect`)+ * 2. request-id resolve + echo + `api.access` log wiring — BEFORE the gates+ * so even gate-rejected responses carry the `x-request-id` echo+ * 3. origin-allowlist CORS with verbatim ACAO reflection + OPTIONS 204+ * 4. mutating-route loopback + workspace-Host gate (DNS-rebinding defense)+ * 5. ephemeral-mode loopback + workspace-Host gate on every `/api/*` read+ * 6. OTel server span wrapping dispatch, the unmatched-route 404, and the+ * duration histogram+ *+ * NOT part of this pipeline: the proxied-request tripwire and the remote-admit+ * Host gate. Those are surface-wide (`/mcp`, static assets, the SPA) and live+ * with the mount (`admitRequestSurface` in `http-app.ts`); the Vite dev server+ * never applied them and must keep not applying them.+ */++import type { IncomingMessage, ServerResponse } from 'node:http';+import { CLIENT_VERSION_HEADER } from '@inkeep/open-knowledge-core';+import { context, propagation, SpanKind, SpanStatusCode } from '@opentelemetry/api';+import {+ ATTR_HTTP_REQUEST_METHOD,+ ATTR_HTTP_RESPONSE_STATUS_CODE,+ ATTR_HTTP_ROUTE,+ ATTR_URL_PATH,+ ATTR_URL_SCHEME,+ ATTR_USER_AGENT_ORIGINAL,+} from '@opentelemetry/semantic-conventions';+import { isAllowedApiOrigin } from '../api-origin.ts';+import { recordEmbedProbe } from '../embed-probe.ts';+import type { PinoLogger } from '../logger.ts';+import {+ isAllowedWorkspaceHostHeader as isAllowedWorkspaceHostHeaderBase,+ isLoopbackAddress,+} from '../loopback.ts';+import { hostHeaderMatchesPublicHost } from '../remote-access.ts';+import { getMeter, getTracer, onTelemetryShutdown } from '../telemetry.ts';+import { errorResponse } from './error-response.ts';+import { REQUEST_ID_HEADER, rememberRequestId, resolveRequestId } from './request-id.ts';++/** Outcome of resolving a pathname against a route table. */+interface ApiRouteResolution {+ /**+ * Low-cardinality route TEMPLATE for the access log, span name, and+ * duration-histogram labels (`/api/tags/:name`, never the raw path) —+ * cardinality discipline for log aggregators and metric labels.+ */+ template: string;+ /**+ * Bound dispatch for the matched handler. Absent means the table owns the+ * URL but nothing handles it (empty `/api/history/` segment, unregistered+ * route) — the pipeline emits the explicit RFC 9457 404 after the gates.+ */+ dispatch?: ((req: IncomingMessage, res: ServerResponse) => Promise<void>) | undefined;+}++/**+ * A router's view of its `/api/*` routes. Two implementations exist during+ * the migration: the legacy dispatch record in `api-extension.ts` (which+ * never declines a URL — unmatched resolves to the `/api/*` template with no+ * dispatch so the pipeline's 404 owns the response) and the native route+ * group (which declines URLs it has not claimed so the caller can fall+ * through to the legacy dispatch with zero side effects).+ */+export interface ApiRouteTable {+ resolve(pathname: string): ApiRouteResolution | null;+ /** Membership in the loopback + workspace-Host mutating gate. */+ isMutating(pathname: string): boolean;+}++export interface ApiPipelineOptions {+ log: PinoLogger;+ /**+ * The tunnel's public host when the server was started with remote access+ * enabled. Widens the browser-Origin allowlist and the workspace-Host+ * predicate the same way the api-extension's local shadows do.+ */+ remotePublicHost?: string;+ /** No-project ephemeral single-file mode — gates EVERY `/api/*` request. */+ ephemeral?: boolean;+ table: ApiRouteTable;+}++/**+ * Returns `true` when the pipeline owned the request (response written or+ * handler dispatched), `false` when the table declined the URL — the caller+ * then falls through to its next dispatch layer. Rejects when a handler+ * throws (the RFC 9457 500 is already on the wire; callers log and move on).+ */+export type ApiRequestPipeline = (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;++// Cache the HTTP duration histogram at module scope — lazy-init at first use+// so the meter is a real meter (post-`initTelemetry`), not the pre-init no-op.+// Recreating the histogram every request allocates + registers a fresh+// instrument on every hit.+let _httpDurationHist: ReturnType<ReturnType<typeof getMeter>['createHistogram']> | null = null;+// Reset on provider teardown so a shutdownTelemetry + initTelemetry cycle+// (dev-server restart, test harness) re-registers against the fresh provider+// instead of silently recording into the dead one. Same pattern as+// `parse-pool.ts`.+onTelemetryShutdown(() => {+ _httpDurationHist = null;+});+function httpDurationHist(): ReturnType<ReturnType<typeof getMeter>['createHistogram']> {+ _httpDurationHist ||= getMeter().createHistogram('http.server.request.duration', {+ description: 'HTTP server request duration in seconds',+ unit: 's',+ });+ return _httpDurationHist;+}++export function createApiRequestPipeline(opts: ApiPipelineOptions): ApiRequestPipeline {+ const { log, remotePublicHost, ephemeral, table } = opts;+ // In remote mode the tunnel's public Host is as legitimate as a loopback+ // name — the mount's admit gate already vetted it. Same widening the+ // api-extension applies to its route-level Host gates.+ const isAllowedWorkspaceHostHeader = (host: string | undefined): boolean =>+ isAllowedWorkspaceHostHeaderBase(host) ||+ (remotePublicHost !== undefined && hostHeaderMatchesPublicHost(host, remotePublicHost));++ return async (request, response) => {+ const url = request.url?.split('?')[0];+ if (!url) return false;++ const resolution = table.resolve(url);+ if (!resolution) return false;++ // Per-request client-context observation for embed-detection spikes.+ // Pushed into a bounded in-process ring buffer drained by+ // /api/__embed-detect. Assumes loopback-only deployment — the consumer+ // endpoint enforces this. Multi-valued headers (rare) collapse to the+ // joined string Node provides by default for the headers we capture.+ const headerString = (name: string): string | undefined => {+ const value = request.headers[name];+ if (value === undefined) return undefined;+ return Array.isArray(value) ? value.join(', ') : value;+ };+ recordEmbedProbe({+ ts: Date.now(),+ url,+ method: request.method ?? '',+ ua: headerString('user-agent'),+ origin: headerString('origin'),+ referer: headerString('referer'),+ host: headerString('host'),+ remote: request.socket?.remoteAddress,+ secChUa: headerString('sec-ch-ua'),+ secChUaMobile: headerString('sec-ch-ua-mobile'),+ secChUaPlatform: headerString('sec-ch-ua-platform'),+ secFetchSite: headerString('sec-fetch-site'),+ secFetchDest: headerString('sec-fetch-dest'),+ secFetchMode: headerString('sec-fetch-mode'),+ secFetchUser: headerString('sec-fetch-user'),+ });++ const method = request.method ?? 'GET';+ const routeTemplate = resolution.template;++ // Request identity + access log for the /api/* surface. Slots BEFORE the+ // origin/loopback/host gates (without touching their order) so even+ // gate-rejected responses carry the `x-request-id` echo and produce an+ // access-log line. The `typeof` guards mirror the CORS block below —+ // unit-test doubles stub only `writeHead` + `end`.+ const requestId = url.startsWith('/api/') ? resolveRequestId(request) : undefined;+ if (requestId !== undefined) {+ rememberRequestId(request, requestId);+ if (typeof response.setHeader === 'function') {+ response.setHeader(REQUEST_ID_HEADER, requestId);+ }+ if (typeof response.once === 'function') {+ const accessStarted = Date.now();+ let accessLogged = false;+ // One line per request on whichever of finish/close fires first:+ // 'finish' is the fully-flushed response (including long-lived+ // NDJSON streams, logged at stream end); 'close' catches aborted+ // sockets (client disconnect, timeout destroy) that never finish.+ // Route TEMPLATE, never the raw path — cardinality discipline for+ // log aggregators matches the metric-label STOP rule. Byte counts+ // are omitted: Node exposes no cheap per-response counter under+ // chunked encoding (socket.bytesWritten is per-connection).+ const emitAccessLog = () => {+ if (accessLogged) return;+ accessLogged = true;+ log.info(+ {+ event: 'api.access',+ requestId,+ method,+ route: routeTemplate,+ status: response.statusCode,+ durationMs: Date.now() - accessStarted,+ ...(response.writableFinished ? {} : { aborted: true }),+ },+ `${method} ${routeTemplate} ${response.statusCode}`,+ );+ };+ response.once('finish', emitAccessLog);+ response.once('close', emitAccessLog);+ }+ }++ // Origin-allowlist CORS for /api/*. Only loopback origins are accepted:+ // - No Origin header (same-origin browser tab, curl, CLI): passes through.+ // - Origin "null" (Electron packaged renderer, file:// per Fetch spec §4.3): allowed.+ // - http(s)://localhost[:port] / 127.x.x.x[:port] / [::1][:port]: allowed.+ // - Any other Origin: 403 — closes the CSRF door on unauthenticated mutating+ // routes (/api/agent-write-md, /api/rollback, /api/manage/delete, etc.)+ // without breaking the Electron renderer or local Vite dev servers.+ //+ // When an allowed Origin is present, it is reflected verbatim in ACAO (not+ // `*`) so the browser's preflight check passes while non-loopback origins are+ // still refused by the gate above. `Vary: Origin` prevents cache poisoning.+ //+ // Setting via `setHeader` (not `writeHead`) so handler responses that call+ // `writeHead(status, { ... })` inherit these headers. The typeof guard handles+ // unit tests that stub only `writeHead` + `end`.+ if (url.startsWith('/api/')) {+ const origin = request.headers.origin;+ if (origin !== undefined && !isAllowedApiOrigin(origin, remotePublicHost)) {+ // RFC 9457 problem+json. Tag the handler as `api-origin-gate` so+ // the `ok.api.error.count` counter distinguishes onRequest-level+ // CSRF rejections from per-handler emits. The cross-origin browser+ // can't read the body anyway (CORS strips it) but consistent wire+ // shape lets server-to-server callers + tests parse uniformly.+ errorResponse(response, 403, 'urn:ok:error:invalid-origin', 'Origin not allowed.', {+ handler: 'api-origin-gate',+ });+ return true;+ }+ if (typeof response.setHeader === 'function') {+ if (origin !== undefined) {+ response.setHeader('Access-Control-Allow-Origin', origin);+ response.setHeader('Vary', 'Origin');+ }+ response.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');+ // Content-Type/Authorization: standard request headers. traceparent/+ // tracestate/baggage: OTel W3C trace-context propagation from the+ // browser SDK. x-ok-client-*: the client→version metadata the renderer+ // stamps on every /api/* request (clientVersionHeaders) — omitting+ // these fails the preflight for the cross-origin renderer (dev Vite+ // origin / file:// packaged) before the real request fires.+ response.setHeader(+ 'Access-Control-Allow-Headers',+ `Content-Type, Authorization, traceparent, tracestate, baggage, ${REQUEST_ID_HEADER}, ${CLIENT_VERSION_HEADER.protocol}, ${CLIENT_VERSION_HEADER.runtime}, ${CLIENT_VERSION_HEADER.kind}`,+ );+ // Let cross-origin renderer JS read the correlation ID echo — CORS+ // hides non-safelisted response headers by default.+ response.setHeader('Access-Control-Expose-Headers', REQUEST_ID_HEADER);+ }+ // OPTIONS preflight — short-circuit with 204 + the headers above.+ if (request.method === 'OPTIONS') {+ response.writeHead(204);+ response.end();+ return true;+ }+ }++ // DNS-rebinding defense for state-mutating endpoints. The+ // `isLoopbackAddress` TCP-peer check and `isAllowedWorkspaceHostHeader`+ // Host-header check together block the standard rebinding pattern+ // (attacker-owned hostname whose DNS resolves to 127.0.0.1 after an+ // initial attacker-serves-JS response — the TCP peer is loopback,+ // but the Host header names the attacker domain). The same mitigation+ // already gates `/api/workspace`; without it, a rebinding page could+ // POST /api/upload + /api/agent-write, mutating the local vault.+ //+ // Test-harness note: Node's production socket always has+ // `remoteAddress` set by the kernel; the only path that reaches+ // this check without a socket is a mocked `IncomingMessage` built+ // from `Readable.from(...)`. Those mocks bypass the HTTP listener+ // entirely and can't be reached by a real remote attacker, so a+ // missing socket is treated as test-context and skips the check.+ // The Host-header gate still fires (tests set `host: 'localhost'`),+ // so the protection remains meaningful for any production path.+ if (table.isMutating(url)) {+ const peerAddress = request.socket?.remoteAddress;+ if (peerAddress !== undefined && !isLoopbackAddress(peerAddress)) {+ errorResponse(response, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {+ handler: 'api-mutating-gate',+ });+ return true;+ }+ if (!isAllowedWorkspaceHostHeader(request.headers.host)) {+ errorResponse(response, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {+ handler: 'api-mutating-gate',+ });+ return true;+ }+ }++ // No-project ephemeral single-file mode (`ok <file>`) sets contentDir to+ // the opened file's PARENT — often a user-data dir (~/Downloads,+ // ~/Documents). Several read routes (`/api/asset`, `/api/asset-text`,+ // `/api/document`) return bytes under contentDir bounded only by+ // `isWithinContentDir`, NOT by the single-file content scope (which is+ // enforced at the indexing/listing layer, not the byte-read path). So+ // without a host gate a DNS-rebound page could exfiltrate sibling files.+ // Apply the same loopback + workspace-host check the mutating gate uses to+ // EVERY `/api/*` request in ephemeral mode — one choke point, so future+ // read routes inherit it rather than each needing its own gate. Project /+ // desktop modes (`ephemeral` falsy) keep their prior origin-only posture+ // for reads (the user chose the served root there); this mirrors the+ // ephemeral-scoped content-asset gate in `mcp-mount.ts`, which covers the+ // non-`/api/` static-serve path.+ if (ephemeral && url.startsWith('/api/')) {+ const peerAddress = request.socket?.remoteAddress;+ if (peerAddress !== undefined && !isLoopbackAddress(peerAddress)) {+ errorResponse(response, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {+ handler: 'api-ephemeral-gate',+ });+ return true;+ }+ if (!isAllowedWorkspaceHostHeader(request.headers.host)) {+ errorResponse(response, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {+ handler: 'api-ephemeral-gate',+ });+ return true;+ }+ }++ // Only /api/* gets a server span. Non-API routes (static file serving,+ // Hocuspocus's own paths) fall through silently. (Route dispatch+ // happens inside the OTel active-span block below.)+ if (!url.startsWith('/api/')) return false;++ // Extract incoming trace context (W3C traceparent header) so this server+ // span attaches as a child of the browser-initiated trace.+ const extractedCtx = propagation.extract(context.active(), request.headers);++ const tracer = getTracer();+ const started = Date.now();+ await context.with(extractedCtx, () =>+ tracer.startActiveSpan(+ `HTTP ${method} ${routeTemplate}`,+ {+ kind: SpanKind.SERVER,+ attributes: {+ [ATTR_HTTP_REQUEST_METHOD]: method,+ [ATTR_HTTP_ROUTE]: routeTemplate,+ [ATTR_URL_PATH]: url,+ [ATTR_URL_SCHEME]: 'http',+ [ATTR_USER_AGENT_ORIGINAL]: request.headers['user-agent'] ?? '',+ // Correlation ID (UUID or client-supplied bounded token) — a+ // sanctioned span attribute like `ok.error.instance`; the+ // cardinality STOP rule governs metric labels, which stay+ // request-id-free.+ 'ok.request.id': requestId,+ },+ },+ async (span) => {+ try {+ const dispatch = resolution.dispatch;+ if (dispatch !== undefined) {+ await dispatch(request, response);+ } else {+ // Defense-in-depth: unmatched `/api/*` routes (typos, removed+ // endpoints, empty `/api/rescue/` / `/api/history/` segments)+ // would otherwise fall through with no response body, leaving+ // Hocuspocus's `onRequest` machinery to either pass through to+ // static-file middleware or hang. Emit an explicit RFC 9457 404+ // so the dispatch surface is fully closed.+ //+ // `detail` echoes the actual requested URL (no information+ // leak — the client sent it). `routeTemplate` is bounded+ // to `/api/*` for unmatched routes and used only for+ // histogram labels / span attributes upstream — keeping+ // the two concerns separate so the wire-detail stays+ // actionable for debuggers without coupling to the+ // cardinality-bounded telemetry surface.+ errorResponse(response, 404, 'urn:ok:error:not-found', 'API endpoint not found.', {+ handler: 'api-dispatch',+ detail: `No handler for ${method} ${url}`,+ });+ }++ const status = response.statusCode;+ span.setAttribute(ATTR_HTTP_RESPONSE_STATUS_CODE, status);+ if (status >= 500) {+ span.setStatus({ code: SpanStatusCode.ERROR, message: `status ${status}` });+ }+ } catch (err) {+ span.recordException(err as Error);+ span.setStatus({+ code: SpanStatusCode.ERROR,+ message: err instanceof Error ? err.message : String(err),+ });+ // Last-resort RFC 9457 envelope. Per-handler try/catch is the+ // primary error boundary, but a synchronous throw before any+ // response write would otherwise reach the client as a+ // connection reset (or Hocuspocus default error handling) —+ // not the typed application/problem+json envelope SDK+ // consumers parse. Guard on+ // `!headersSent && !writableEnded && !destroyed` so we+ // don't double-emit when the inner handler already wrote a+ // response or the socket was destroyed mid-handler — same+ // three-way guard `createStreamingErrorWriter` uses for+ // mid-stream emission. Handler tag is the matched route+ // template so telemetry attributes a 5xx surge to the+ // failing endpoint.+ if (!response.headersSent && !response.writableEnded && !response.destroyed) {+ errorResponse(+ response,+ 500,+ 'urn:ok:error:internal-server-error',+ 'Internal server error.',+ {+ handler: routeTemplate,+ cause: err,+ },+ );+ }+ // Error spans carry the HTTP status attribute too (OTel HTTP+ // server semconv) — the try-path stamp above never ran, and+ // trace UIs filter error spans by status code.+ span.setAttribute(ATTR_HTTP_RESPONSE_STATUS_CODE, response.statusCode);+ // Re-throw so the caller's error machinery logs the exception —+ // the legacy dispatch surfaces it through Hocuspocus's onRequest+ // extension chain, the native mount through its own catch. The+ // response is already ended (either by errorResponse above or by+ // an earlier handler write), so Hocuspocus 4.x treats this as a+ // post-response observation, not a connection-level failure.+ // Verify this assumption holds when bumping Hocuspocus —+ // version-specific reaction to throws from onRequest is+ // framework-internal behavior.+ throw err;+ } finally {+ span.end();+ const durSec = (Date.now() - started) / 1000;+ httpDurationHist().record(durSec, {+ [ATTR_HTTP_REQUEST_METHOD]: method,+ [ATTR_HTTP_ROUTE]: routeTemplate,+ [ATTR_HTTP_RESPONSE_STATUS_CODE]: response.statusCode,+ });+ }+ },+ ),+ );+ return true;+ };+}diff --git a/packages/server/src/http/http-app.test.ts b/packages/server/src/http/http-app.test.tsindex e900d2cfd..739c4e95d 100644--- a/packages/server/src/http/http-app.test.ts+++ b/packages/server/src/http/http-app.test.ts@@ -1,7 +1,11 @@import { createServer } from 'node:http';import { describe, expect, test } from 'vitest';import { listenOnLoopback } from '../loopback-rig-test-helpers.ts';-import { type CreateHttpAppOptions, createHttpApp } from './http-app.ts';+import {+ assertSingleRouterOwnership,+ type CreateHttpAppOptions,+ createHttpApp,+} from './http-app.ts';/*** Adapter-boundary pins the composition suite cannot see: these assert@@ -87,3 +91,34 @@ describe('createHttpApp adapter boundary', () => {}});});++describe('assertSingleRouterOwnership', () => {+ test('throws when a native path also exists in the legacy record', () => {+ expect(() =>+ assertSingleRouterOwnership(['/api/backlinks', '/api/tags/*'], {+ '/api/backlinks': async () => {},+ }),+ ).toThrow(+ 'route(s) present in both the legacy dispatch record and a native route group: /api/backlinks',+ );+ });++ test('throws when a legacy record key falls under a native wildcard namespace', () => {+ expect(() =>+ assertSingleRouterOwnership(['/api/tags/*'], {+ '/api/tags/special': async () => {},+ }),+ ).toThrow('/api/tags/special (under a native wildcard)');+ });++ test('passes for disjoint sets, including a legacy key at the wildcard base', () => {+ expect(() =>+ assertSingleRouterOwnership(['/api/backlinks', '/api/tags/*'], {+ '/api/documents': async () => {},+ // The base path is OUTSIDE the wildcard's namespace ('/api/tags/*'+ // claims '/api/tags/…', not '/api/tags' itself).+ '/api/tags': async () => {},+ }),+ ).not.toThrow();+ });+});diff --git a/packages/server/src/http/http-app.ts b/packages/server/src/http/http-app.tsindex 5d7586f59..da294afff 100644--- a/packages/server/src/http/http-app.ts+++ b/packages/server/src/http/http-app.ts@@ -3,6 +3,11 @@ import { getRequestListener, type HttpBindings } from '@hono/node-server';import { RESPONSE_ALREADY_SENT } from '@hono/node-server/utils/response';import { Hono } from 'hono';import type { PinoLogger } from '../logger.ts';+import {+ hasForwardingHeaders,+ isRemoteAdmitted,+ type ResolvedRemoteAccess,+} from '../remote-access.ts';import { errorResponse } from './error-response.ts';/**@@ -29,11 +34,116 @@ export interface HealthProvider {degraded: () => readonly string[];}+/**+ * A router-agnostic bundle of natively-served `/api/*` routes: the Hono+ * patterns to claim ahead of the strangler catch-all, plus the shared+ * admission pipeline (`http/api-pipeline.ts`) bound to the native route+ * table. `dispatch` returns `false` when the table declines the URL — the+ * mount then falls through to the legacy dispatch. That decline is+ * reachable: Hono matches against a normalized path (dot segments resolved,+ * non-reserved percent-escapes decoded) while the pipeline resolves the raw+ * `req.url`, so requests like `/api/./backlinks` are claimed by the router+ * and declined by the table.+ */+export interface NativeApiHandle {+ paths: readonly string[];+ dispatch: (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;+}++/**+ * The surface-wide admission prelude every request runs before dispatch —+ * shared verbatim between the legacy `mcp-mount` dispatch and natively-mounted+ * `/api/*` routes (which sit above the strangler catch-all and would otherwise+ * bypass it). Returns `false` after writing the 403 when the request is+ * refused.+ *+ * Gate 1 — tripwire: proxy-forwarding headers on a server that never opted+ * into remote access mean a tunnel is pointed at us. Refuse with the fix+ * instruction — the alternative is silently serving a public tunnel with full+ * local trust, decided by whether the tunnel rewrites Host.+ *+ * Gate 2 — with remote access enabled, ONE admit decision covers every+ * surface (trust-the-tunnel — see remote-access.ts): loopback socket + Host on+ * the allowlist (loopback names or the tunnel's public host). Refusals are+ * wrong-Host callers (DNS-rebound pages), not auth failures.+ *+ * `handler` is the caller's tag on the `ok.api.error.count` counter for+ * rejections ('mcp-mount' for the legacy dispatch, 'native-api-surface' for+ * the native mount) — the primary triage dimension, so refusals attribute to+ * the surface that actually refused.+ */+export function admitRequestSurface(+ req: IncomingMessage,+ res: ServerResponse,+ remoteAccess: ResolvedRemoteAccess | undefined,+ handler: string,+): boolean {+ if (remoteAccess === undefined && hasForwardingHeaders(req)) {+ errorResponse(+ res,+ 403,+ 'urn:ok:error:host-not-allowed',+ 'Proxied request refused: this server was not started for remote access. Restart with `ok start --remote` to serve through a tunnel.',+ { handler },+ );+ return false;+ }+ if (remoteAccess !== undefined && !isRemoteAdmitted(req, remoteAccess)) {+ errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {+ handler,+ });+ return false;+ }+ return true;+}++/**+ * "A route lives in exactly one router" — the mechanical form. A path+ * claimed by a native group that still has a legacy record entry would+ * silently shadow it (the native mount dispatches first), leaving+ * live-looking dead code in the legacy dispatch. Callers invoke this at+ * construction so the overlap fails the boot instead. Both directions are+ * checked: a native exact path that is also a legacy record key, and a+ * legacy record key that falls under a native wildcard's namespace (the+ * wildcard claims everything below its prefix, so such a key is just as+ * shadowed as an exact duplicate).+ */+export function assertSingleRouterOwnership(+ nativePaths: readonly string[],+ legacyRoutes: Readonly<Record<string, unknown>>,+): void {+ const doubleRouted = nativePaths.filter((p) => !p.includes('*') && p in legacyRoutes);+ const wildcardPrefixes = nativePaths.filter((p) => p.endsWith('/*')).map((p) => p.slice(0, -1));+ const shadowed = Object.keys(legacyRoutes)+ .filter((key) => wildcardPrefixes.some((prefix) => key.startsWith(prefix)))+ .map((key) => `${key} (under a native wildcard)`);+ const conflicts = [...doubleRouted, ...shadowed];+ if (conflicts.length > 0) {+ throw new Error(+ `route(s) present in both the legacy dispatch record and a native route group: ${conflicts.join(', ')}`,+ );+ }+}+export interface CreateHttpAppOptions {/** Readiness provider for /readyz; omitted means always-ready (harnesses with synchronous init). */health?: HealthProvider;/** The pre-router dispatch. Every route without a native handler flows through here unchanged. */legacyDispatch: (req: IncomingMessage, res: ServerResponse) => void;+ /**+ * Natively-served `/api/*` routes, mounted ABOVE the strangler catch-all.+ * Each claimed path runs the same surface admission gates the legacy+ * dispatch applies (`admitRequestSurface`) and then the shared `/api/*`+ * pipeline via `dispatch` — so a ported route keeps byte-identical gate+ * behavior while never reaching the legacy dispatch.+ */+ nativeApi?: NativeApiHandle;+ /**+ * Resolved `remote:` config for the surface admission gates on native+ * routes (same value the mount applies to the legacy dispatch). Undefined+ * ⇒ remote access disabled (the tripwire refuses proxied requests).+ */+ remoteAccess?: ResolvedRemoteAccess | undefined;/** Structured logger for handler errors the router catches. */log: PinoLogger;}@@ -111,6 +221,54 @@ export function createHttpApp(opts: CreateHttpAppOptions): HttpAppHandle {});}+ // Natively-served /api/* routes, ABOVE the strangler catch-all. Each runs+ // the surface admission gates first (the tripwire + remote-admit pair the+ // legacy dispatch applies in mcp-mount's onRequest), then the shared+ // /api/* pipeline — request-id, CORS, DNS-rebinding gates, dispatch span.+ const nativeApi = opts.nativeApi;+ if (nativeApi !== undefined) {+ for (const path of nativeApi.paths) {+ app.all(path, async (c) => {+ const req = c.env.incoming;+ const res = c.env.outgoing;+ if (!admitRequestSurface(req, res, opts.remoteAccess, 'native-api-surface')) {+ return RESPONSE_ALREADY_SENT;+ }+ try {+ const handled = await nativeApi.dispatch(req, res);+ // Reachable: Hono routes on a NORMALIZED path (`@hono/node-server`+ // resolves dot segments, and strict-mode `getPath` percent-decodes),+ // while the pipeline re-derives the path from the untouched+ // `c.env.incoming.url`. So `/api/./backlinks` and `/api/back%6Cinks`+ // get claimed here and then declined by the table. The legacy+ // dispatch owns every URL the native table does not; this branch is+ // what keeps those requests from hanging with no response written.+ if (!handled) opts.legacyDispatch(req, res);+ } catch (err) {+ // Mirrors the legacy dispatch's posture for onRequest rejections:+ // the pipeline already emitted the typed 500 before rethrowing, so+ // this is log-only unless the response never started.+ opts.log.error({ err }, 'Unhandled onRequest error');+ if (!res.writableEnded && !res.headersSent) {+ errorResponse(+ res,+ 500,+ 'urn:ok:error:internal-server-error',+ 'Internal server error.',+ {+ handler: 'native-api-catch',+ cause: err,+ },+ );+ } else if (!res.writableEnded) {+ res.end();+ }+ }+ return RESPONSE_ALREADY_SENT;+ });+ }+ }+// Strangler catch-all: hand the raw req/res to the legacy dispatch and// tell the adapter the response is owned elsewhere. The legacy handlers// finish asynchronously; Node keeps the response open until they end it.diff --git a/packages/server/src/http/link-graph-routes.ts b/packages/server/src/http/link-graph-routes.tsnew file mode 100644index 000000000..ea131be65--- /dev/null+++ b/packages/server/src/http/link-graph-routes.ts@@ -0,0 +1,583 @@+/**+ * The link/graph read family — `backlinks`, `backlink-counts`,+ * `forward-links`, `link-graph`, `dead-links`, `tags-list`, `tags-for-name`,+ * `suggest-links` — lifted out of `api-extension.ts` as the first natively-+ * routed Wave 2 group. Same lift shape as `skills-sh-handlers.ts`: what the+ * handlers closed over in the extension arrives as+ * {@link LinkGraphRouteDeps}, and the handler bodies are unchanged.+ *+ * Unlike the skills.sh handlers, this group does NOT return to the legacy+ * route table: `createLinkGraphRoutes` returns an {@link ApiRouteTable} ++ * the Hono patterns for the native mount, and the extension exposes them as+ * its `nativeApi` handle. A route lives in exactly one router — these paths+ * are gone from the legacy dispatch record in the same change.+ */++import type { IncomingMessage, ServerResponse } from 'node:http';+import type { Hocuspocus } from '@hocuspocus/server';+import {+ BacklinkCountsSuccessSchema,+ BacklinksSuccessSchema,+ DeadLinksSuccessSchema,+ EmptyRequestSchema,+ ForwardLinksSuccessSchema,+ LinkGraphSuccessSchema,+ SuggestLinksSuccessSchema,+ TagsForNameSuccessSchema,+ TagsListSuccessSchema,+} from '@inkeep/open-knowledge-core';+import { isConfigDoc, isSystemDoc } from '../cc1-broadcast.ts';+import type { DerivedDocumentIndexApiPort, DerivedGraphNode } from '../derived-document-index.ts';+import type { FileIndexEntry } from '../file-watcher.ts';+import type { FrontmatterMetadata } from '../page-identity.ts';+import { SuggestLinksTargetNotFoundError, suggestLinks } from '../suggest-links.ts';+import type { ApiRouteTable } from './api-pipeline.ts';+import { errorResponse } from './error-response.ts';+import { withValidation } from './request-validation.ts';+import { successResponse } from './success-response.ts';++export interface LinkGraphRouteDeps {+ hocuspocus: Hocuspocus;+ derivedDocumentIndex: DerivedDocumentIndexApiPort | undefined;+ getFileIndex: () => ReadonlyMap<string, FileIndexEntry>;+ /** The extension's docName safety predicate (path-traversal refusal). */+ isSafeDocName: (docName: string) => boolean;+ readPageTitleForDocName: (docName: string) => string;+ readPageTitleForLinkedDocName: (docName: string, admitted: Set<string>) => string;+ readFrontmatterMetadataForLinkedDocName: (+ docName: string,+ admitted: Set<string>,+ ) => FrontmatterMetadata;+ collectAdmittedDocNames: () => Promise<Set<string>>;+ resolveAlias: (docName: string) => string;+ respondToDerivedIndexQueryFailure: (+ res: ServerResponse,+ err: unknown,+ options: { handler: string; failureTitle: string },+ ) => void;+}++export interface LinkGraphRoutes {+ /** Hono patterns for the native mount (`NativeApiHandle.paths`). */+ paths: readonly string[];+ /** The group's view for the shared /api/* admission pipeline. */+ table: ApiRouteTable;+}++export function createLinkGraphRoutes(deps: LinkGraphRouteDeps): LinkGraphRoutes {+ const {+ hocuspocus,+ derivedDocumentIndex,+ getFileIndex,+ isSafeDocName,+ readPageTitleForDocName,+ readPageTitleForLinkedDocName,+ readFrontmatterMetadataForLinkedDocName,+ collectAdmittedDocNames,+ resolveAlias,+ respondToDerivedIndexQueryFailure,+ } = deps;++ const handleBacklinks = withValidation(+ EmptyRequestSchema,+ async (req, res) => {+ if (!derivedDocumentIndex) {+ errorResponse(+ res,+ 503,+ 'urn:ok:error:backlink-index-not-configured',+ 'Backlink index is not configured.',+ { handler: 'backlinks' },+ );+ return;+ }+ try {+ const url = new URL(req.url ?? '', 'http://localhost');+ const docName = url.searchParams.get('docName');+ if (!docName) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing docName parameter.', {+ handler: 'backlinks',+ });+ return;+ }+ if (!isSafeDocName(docName)) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {+ handler: 'backlinks',+ });+ return;+ }+ const backlinks = (await derivedDocumentIndex.getBacklinks(docName)).map((entry) => ({+ source: entry.source,+ anchor: entry.anchor,+ title: readPageTitleForDocName(entry.source),+ snippet: entry.snippet,+ }));+ successResponse(+ res,+ 200,+ BacklinksSuccessSchema,+ { docName, backlinks },+ { handler: 'backlinks' },+ );+ } catch (e) {+ respondToDerivedIndexQueryFailure(res, e, {+ handler: 'backlinks',+ failureTitle: 'Failed to read backlinks.',+ });+ }+ },+ { handler: 'backlinks', method: 'GET', skipBodyParse: true },+ );++ /**+ * Bulk backlink-count lookup. `GET /api/backlink-counts?docNames=a,b,c`+ * returns `{ counts: { a: 3, b: 0, c: 2 } }`. Serves listing UIs+ * (exec ls/grep/find slim enrichment) that need connection density per file+ * without N-amplifying the single-doc `/api/backlinks` endpoint.+ * docNames failing `isSafeDocName` are silently dropped from `counts`.+ */+ const handleBacklinkCounts = withValidation(+ EmptyRequestSchema,+ async (req, res) => {+ if (!derivedDocumentIndex) {+ errorResponse(+ res,+ 503,+ 'urn:ok:error:backlink-index-not-configured',+ 'Backlink index is not configured.',+ { handler: 'backlink-counts' },+ );+ return;+ }+ try {+ const url = new URL(req.url ?? '', 'http://localhost');+ const raw = url.searchParams.get('docNames');+ if (!raw) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing docNames parameter.', {+ handler: 'backlink-counts',+ });+ return;+ }+ const docNames = raw+ .split(',')+ .map((docName) => docName.trim())+ .filter((docName) => docName && isSafeDocName(docName));+ const counts = await derivedDocumentIndex.getBacklinkCounts(docNames);+ successResponse(+ res,+ 200,+ BacklinkCountsSuccessSchema,+ { counts },+ { handler: 'backlink-counts' },+ );+ } catch (e) {+ respondToDerivedIndexQueryFailure(res, e, {+ handler: 'backlink-counts',+ failureTitle: 'Failed to read backlink counts.',+ });+ }+ },+ { handler: 'backlink-counts', method: 'GET', skipBodyParse: true },+ );++ const handleForwardLinks = withValidation(+ EmptyRequestSchema,+ async (req, res) => {+ if (!derivedDocumentIndex) {+ errorResponse(+ res,+ 503,+ 'urn:ok:error:backlink-index-not-configured',+ 'Backlink index is not configured.',+ { handler: 'forward-links' },+ );+ return;+ }+ try {+ const url = new URL(req.url ?? '', 'http://localhost');+ const docName = url.searchParams.get('docName');+ if (!docName) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing docName parameter.', {+ handler: 'forward-links',+ });+ return;+ }+ if (!isSafeDocName(docName)) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {+ handler: 'forward-links',+ });+ return;+ }+ const admitted = await collectAdmittedDocNames();+ successResponse(+ res,+ 200,+ ForwardLinksSuccessSchema,+ {+ docName,+ forwardLinks: (await derivedDocumentIndex.getForwardLinkEntries(docName)).map(+ (entry) =>+ entry.kind === 'doc'+ ? {+ kind: 'doc' as const,+ docName: entry.target,+ anchor: entry.anchor,+ title: readPageTitleForLinkedDocName(entry.target, admitted),+ snippet: entry.snippet,+ }+ : {+ kind: 'external' as const,+ url: entry.url,+ title: entry.label ?? entry.url,+ snippet: entry.snippet,+ },+ ),+ },+ { handler: 'forward-links' },+ );+ } catch (e) {+ respondToDerivedIndexQueryFailure(res, e, {+ handler: 'forward-links',+ failureTitle: 'Failed to read forward links.',+ });+ }+ },+ { handler: 'forward-links', method: 'GET', skipBodyParse: true },+ );++ const handleLinkGraph = withValidation(+ EmptyRequestSchema,+ async (req, res) => {+ if (!derivedDocumentIndex) {+ errorResponse(+ res,+ 503,+ 'urn:ok:error:backlink-index-not-configured',+ 'Backlink index is not configured.',+ { handler: 'link-graph' },+ );+ return;+ }+ try {+ const url = new URL(req.url ?? '', 'http://localhost');+ const docName = url.searchParams.get('docName');+ if (docName && !isSafeDocName(docName)) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {+ handler: 'link-graph',+ });+ return;+ }++ const rawDegrees = url.searchParams.get('degrees');+ if (rawDegrees && !docName) {+ errorResponse(+ res,+ 400,+ 'urn:ok:error:invalid-request',+ 'docName is required when degrees is provided.',+ { handler: 'link-graph' },+ );+ return;+ }++ let nodes: DerivedGraphNode[];+ let links: Array<{ source: string; target: string }>;++ if (rawDegrees && docName) {+ const degrees = Number.parseInt(rawDegrees, 10);+ if (!Number.isFinite(degrees) || degrees < 0) {+ errorResponse(+ res,+ 400,+ 'urn:ok:error:invalid-request',+ 'degrees must be a non-negative integer.',+ { handler: 'link-graph' },+ );+ return;+ }++ ({ nodes, links } = await derivedDocumentIndex.getLinkGraphNeighborhood(+ docName,+ degrees,+ ));+ } else {+ ({ nodes, links } = await derivedDocumentIndex.getLinkGraph());+ }++ const admitted = await collectAdmittedDocNames();+ const enrichedNodes = nodes.map((node) => {+ if (node.kind === 'doc') {+ const meta = readFrontmatterMetadataForLinkedDocName(node.docName, admitted);+ return {+ id: node.id,+ kind: 'doc' as const,+ docName: node.docName,+ anchor: node.anchor ?? null,+ label: readPageTitleForLinkedDocName(node.docName, admitted),+ cluster: meta.cluster ?? null,+ category: meta.category ?? null,+ tags: meta.tags ?? null,+ };+ }+ return {+ id: node.id,+ kind: 'external' as const,+ url: node.url,+ label: node.label ?? node.url,+ };+ });+ successResponse(+ res,+ 200,+ LinkGraphSuccessSchema,+ { nodes: enrichedNodes, links },+ { handler: 'link-graph' },+ );+ } catch (e) {+ respondToDerivedIndexQueryFailure(res, e, {+ handler: 'link-graph',+ failureTitle: 'Failed to read link graph.',+ });+ }+ },+ { handler: 'link-graph', method: 'GET', skipBodyParse: true },+ );++ const handleDeadLinks = withValidation(+ EmptyRequestSchema,+ async (req, res) => {+ if (!derivedDocumentIndex) {+ errorResponse(+ res,+ 503,+ 'urn:ok:error:backlink-index-not-configured',+ 'Backlink index is not configured.',+ { handler: 'dead-links' },+ );+ return;+ }+ try {+ const url = new URL(req.url ?? '', 'http://localhost');+ const sourceDocNames = url.searchParams.getAll('sourceDocName');+ if (sourceDocNames.some((docName) => docName.length === 0 || !isSafeDocName(docName))) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid sourceDocName.', {+ handler: 'dead-links',+ });+ return;+ }++ const sourceDocNameFilter = sourceDocNames.length+ ? [...new Set(sourceDocNames.map((docName) => resolveAlias(docName)))]+ : undefined;+ const deadLinks = await derivedDocumentIndex.getDeadLinks(+ await collectAdmittedDocNames(),+ sourceDocNameFilter,+ );++ successResponse(+ res,+ 200,+ DeadLinksSuccessSchema,+ {+ deadLinks: deadLinks.map((entry) => ({+ target: entry.target,+ sources: entry.sources.map((sourceEntry) => ({+ source: sourceEntry.source,+ title: readPageTitleForDocName(sourceEntry.source),+ snippet: sourceEntry.snippet,+ })),+ })),+ },+ { handler: 'dead-links' },+ );+ } catch (e) {+ respondToDerivedIndexQueryFailure(res, e, {+ handler: 'dead-links',+ failureTitle: 'Failed to read dead links.',+ });+ }+ },+ { handler: 'dead-links', method: 'GET', skipBodyParse: true },+ );++ const handleSuggestLinks = withValidation(+ EmptyRequestSchema,+ async (req, res) => {+ try {+ const url = new URL(req.url ?? '', 'http://localhost');+ const docName = url.searchParams.get('docName');+ if (!docName) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing docName parameter.', {+ handler: 'suggest-links',+ });+ return;+ }+ if (!isSafeDocName(docName)) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid docName.', {+ handler: 'suggest-links',+ });+ return;+ }+ if (isSystemDoc(docName) || isConfigDoc(docName)) {+ errorResponse(+ res,+ 400,+ 'urn:ok:error:reserved-doc-name',+ `'${docName}' is a reserved document name.`,+ { handler: 'suggest-links' },+ );+ return;+ }++ const result = await suggestLinks({+ hocuspocus,+ fileIndex: getFileIndex(),+ docName,+ });+ successResponse(res, 200, SuggestLinksSuccessSchema, result, { handler: 'suggest-links' });+ } catch (error) {+ if (error instanceof SuggestLinksTargetNotFoundError) {+ errorResponse(res, 404, 'urn:ok:error:doc-not-found', 'Page not found.', {+ handler: 'suggest-links',+ cause: error,+ });+ return;+ }+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to suggest links.', {+ handler: 'suggest-links',+ cause: error,+ });+ }+ },+ { handler: 'suggest-links', method: 'GET', skipBodyParse: true },+ );++ const handleTagsList = withValidation(+ EmptyRequestSchema,+ async (_req, res) => {+ if (!derivedDocumentIndex) {+ errorResponse(+ res,+ 503,+ 'urn:ok:error:tag-index-not-configured',+ 'Tag index not configured.',+ { handler: 'tags-list' },+ );+ return;+ }+ try {+ const tags = await derivedDocumentIndex.getAllTags();+ successResponse(res, 200, TagsListSuccessSchema, { tags }, { handler: 'tags-list' });+ } catch (e) {+ respondToDerivedIndexQueryFailure(res, e, {+ handler: 'tags-list',+ failureTitle: 'Failed to read tags.',+ });+ }+ },+ { handler: 'tags-list', method: 'GET', skipBodyParse: true },+ );++ async function handleTagsForName(+ req: IncomingMessage,+ res: ServerResponse,+ rawName: string,+ ): Promise<void> {+ if (req.method !== 'GET') {+ errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {+ handler: 'tags-for-name',+ extraHeaders: { Allow: 'GET' },+ });+ return;+ }+ if (!derivedDocumentIndex) {+ errorResponse(+ res,+ 503,+ 'urn:ok:error:tag-index-not-configured',+ 'Tag index not configured.',+ { handler: 'tags-for-name' },+ );+ return;+ }+ let name: string;+ try {+ name = decodeURIComponent(rawName);+ } catch (uriErr) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid tag name encoding.', {+ handler: 'tags-for-name',+ cause: uriErr,+ });+ return;+ }+ if (!name) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing tag name.', {+ handler: 'tags-for-name',+ });+ return;+ }+ try {+ const docs = (await derivedDocumentIndex.getDocsForTagWithMatches(name)).map(+ ({ docName, matchingTags }) => ({+ docName,+ title: readPageTitleForDocName(docName),+ matchingTags,+ snippet: null,+ }),+ );+ successResponse(+ res,+ 200,+ TagsForNameSuccessSchema,+ { name, docs },+ {+ handler: 'tags-for-name',+ },+ );+ } catch (e) {+ respondToDerivedIndexQueryFailure(res, e, {+ handler: 'tags-for-name',+ failureTitle: 'Failed to read tag membership.',+ });+ }+ }++ const routes: Record<string, (req: IncomingMessage, res: ServerResponse) => Promise<void>> = {+ '/api/backlinks': handleBacklinks,+ '/api/backlink-counts': handleBacklinkCounts,+ '/api/forward-links': handleForwardLinks,+ '/api/link-graph': handleLinkGraph,+ '/api/dead-links': handleDeadLinks,+ '/api/tags': handleTagsList,+ '/api/suggest-links': handleSuggestLinks,+ };++ const table: ApiRouteTable = {+ resolve(url) {+ const handler = routes[url];+ if (handler) {+ return { template: url, dispatch: (req, res) => handler(req, res) };+ }+ if (url.startsWith('/api/tags/')) {+ const rawName = url.slice('/api/tags/'.length);+ return {+ template: '/api/tags/:name',+ // Empty name (`/api/tags/`): no dispatch — the pipeline's explicit+ // 404 owns it, under the same template the legacy dispatch used.+ dispatch: rawName ? (req, res) => handleTagsForName(req, res, rawName) : undefined,+ };+ }+ return null;+ },+ // Every route in this group is a read (none rode the legacy+ // MUTATING_ROUTES loopback/Host gate).+ isMutating: () => false,+ };++ return {+ // `/api/tags/*` (not `:name`) so an empty or slash-containing tail+ // reaches the table exactly like the legacy prefix match did.+ paths: [...Object.keys(routes), '/api/tags/*'],+ table,+ };+}diff --git a/packages/server/src/mcp-mount.test.ts b/packages/server/src/mcp-mount.test.tsindex f2a78a841..86cb83aa6 100644--- a/packages/server/src/mcp-mount.test.ts+++ b/packages/server/src/mcp-mount.test.ts@@ -46,6 +46,7 @@ async function startMountedServer(const httpServer = createServer();const mount = mountMcpAndApi({httpServer,+ nativeApi: undefined,hocuspocus: serverHocuspocus,mcpHttpHandler: handler,log,@@ -332,7 +333,7 @@ describe('mountMcpAndApi shutdown drains live WS clients', () => {for (const path of ['/collab', '/collab/keepalive?connectionId=teardown-probe']) {test(`drains live ${path.split('?')[0]} WS so wss.close + httpServer.close resolve promptly`, async () => {const httpServer = createServer();- const mount = mountMcpAndApi({ httpServer, hocuspocus, log });+ const mount = mountMcpAndApi({ httpServer, nativeApi: undefined, hocuspocus, log });const port = await getFreeLoopbackPort();await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', () => resolve()));@@ -405,6 +406,7 @@ describe('mountMcpAndApi content-asset middleware', () => {};const mount = mountMcpAndApi({httpServer,+ nativeApi: undefined,hocuspocus,log,contentAssetMiddleware: createAssetServeMiddleware({@@ -477,6 +479,7 @@ describe('mountMcpAndApi content-asset middleware', () => {const httpServer = createServer();const mount = mountMcpAndApi({httpServer,+ nativeApi: undefined,hocuspocus,log,contentAssetMiddleware: () => {@@ -521,6 +524,7 @@ describe('mountMcpAndApi ephemeral content-asset gate', () => {const httpServer = createServer();const mount = mountMcpAndApi({httpServer,+ nativeApi: undefined,hocuspocus,log,ephemeral,@@ -599,6 +603,7 @@ describe('mountMcpAndApi react-shell middleware', () => {const httpServer = createServer();const mount = mountMcpAndApi({httpServer,+ nativeApi: undefined,hocuspocus,log,contentAssetMiddleware: opts?.contentAssetMiddleware,diff --git a/packages/server/src/mcp-mount.ts b/packages/server/src/mcp-mount.tsindex 4cfbf923b..d4d8c4ee7 100644--- a/packages/server/src/mcp-mount.ts+++ b/packages/server/src/mcp-mount.ts@@ -31,16 +31,17 @@ import type { AgentSessionManager } from './agent-sessions.ts';import { isAllowedApiOrigin } from './api-origin.ts';import { createCollaborationHost } from './collaboration-host.ts';import { errorResponse } from './http/error-response.ts';-import { createHttpApp, type HealthProvider } from './http/http-app.ts';+import {+ admitRequestSurface,+ createHttpApp,+ type HealthProvider,+ type NativeApiHandle,+} from './http/http-app.ts';import type { PinoLogger } from './logger.ts';import { isAllowedWorkspaceHostHeader, isLoopbackAddress } from './loopback.ts';import type { MaintenanceCoordinator } from './maintenance-coordinator.ts';import type { McpHttpHandler } from './mcp-http.ts';-import {- hasForwardingHeaders,- isRemoteAdmitted,- type ResolvedRemoteAccess,-} from './remote-access.ts';+import { hasForwardingHeaders, type ResolvedRemoteAccess } from './remote-access.ts';export type { ReadinessState } from './http/http-app.ts';@@ -139,6 +140,16 @@ export interface MountMcpAndApiOptions {* health routes still mount and report ready with no degraded subsystems.*/health?: HealthProvider;+ /**+ * Natively-served `/api/*` route groups (the `ServerInstance.nativeApi`+ * handle). When supplied, the Hono app claims these paths ahead of the+ * strangler catch-all and runs them through the shared admission pipeline.+ * Required-but-undefinable rather than optional: forgetting the wiring at+ * a mount site would silently 404 every ported route out of the legacy+ * dispatch, so passing `undefined` (harnesses that never touch ported+ * routes) must be an explicit decision, not an omission.+ */+ nativeApi: NativeApiHandle | undefined;/*** Resolved `remote:` config (null/undefined ⇒ remote access disabled).* When set, EVERY surface (`/mcp`, `/api/*`, `/collab`, content assets,@@ -215,30 +226,11 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandlconst onRequest = (req: IncomingMessage, res: ServerResponse): void => {const url = req.url?.split('?')[0];- // Tripwire: proxy-forwarding headers on a server that never opted into- // remote access mean a tunnel is pointed at us. Refuse with the fix- // instruction — the alternative is silently serving a public tunnel with- // full local trust, decided by whether the tunnel rewrites Host.- if (remoteAccess === undefined && hasForwardingHeaders(req)) {- errorResponse(- res,- 403,- 'urn:ok:error:host-not-allowed',- 'Proxied request refused: this server was not started for remote access. Restart with `ok start --remote` to serve through a tunnel.',- { handler: 'mcp-mount' },- );- return;- }- // With remote access enabled, ONE admit decision covers every surface- // (trust-the-tunnel — see remote-access.ts): loopback socket + Host on- // the allowlist (loopback names or the tunnel's public host). Refusals- // are wrong-Host callers (DNS-rebound pages), not auth failures.- if (remoteAccess !== undefined && !isRemoteAdmitted(req, remoteAccess)) {- errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {- handler: 'mcp-mount',- });- return;- }+ // Surface-wide admission prelude — the proxied-request tripwire plus the+ // remote-access admit decision. Shared with the natively-mounted /api/*+ // routes (`admitRequestSurface` in http-app.ts), which sit above the+ // strangler catch-all and would otherwise bypass it.+ if (!admitRequestSurface(req, res, remoteAccess, 'mcp-mount')) return;if (mcpHttpHandler !== undefined && url === '/mcp') {const origin = req.headers.origin;const sessionId = Array.isArray(req.headers['mcp-session-id'])@@ -445,12 +437,14 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandlsocket.destroy();};- // The canonical Hono app owns top-level routing (health natively; every- // unmigrated surface falls through its catch-all into `onRequest`- // unchanged). The WS upgrade path stays a raw listener — it never routes- // through HTTP dispatch.+ // The canonical Hono app owns top-level routing (health + ported /api/*+ // groups natively; every unmigrated surface falls through its catch-all+ // into `onRequest` unchanged). The WS upgrade path stays a raw listener —+ // it never routes through HTTP dispatch.const { requestListener } = createHttpApp({health: opts.health,+ nativeApi: opts.nativeApi,+ remoteAccess,legacyDispatch: onRequest,log,});diff --git a/packages/server/src/remote-mcp.test.ts b/packages/server/src/remote-mcp.test.tsindex 48eded014..85e380039 100644--- a/packages/server/src/remote-mcp.test.ts+++ b/packages/server/src/remote-mcp.test.ts@@ -101,6 +101,7 @@ async function bootRemoteRig(const httpServer: HttpServer = createHttpServer();const mount: MountMcpAndApiHandle = mountMcpAndApi({httpServer,+ nativeApi: undefined,hocuspocus,mcpHttpHandler: handler,remoteAccess,diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.tsindex 8ea18aa26..788943053 100644--- a/packages/server/src/server-factory.ts+++ b/packages/server/src/server-factory.ts@@ -132,6 +132,7 @@ import type {} from './github-permissions.ts';import { type HeadWatcherHandle, readProjectHeadState, startHeadWatcher } from './head-watcher.ts';import { errnoCode } from './http/handler-utils.ts';+import type { NativeApiHandle } from './http/http-app.ts';import { scanGlobalInPlaceSkills, scanInPlaceSkillDirs } from './in-place-skills.ts';import { createLiveDerivedIndexExtension } from './live-derived-index.ts';import { getLogger } from './logger.ts';@@ -401,6 +402,13 @@ export interface ServerOptions {export interface ServerInstance {hocuspocus: Hocuspocus;sessionManager: AgentSessionManager;+ /**+ * Natively-routed /api/* groups (paths + the shared admission pipeline+ * bound to their table). Callers that mount HTTP dispatch — `bootServer`+ * via `mountMcpAndApi`, the Vite dev plugin, the integration harness —+ * MUST wire this in, or the ported routes 404 out of the legacy dispatch.+ */+ nativeApi: NativeApiHandle;cc1Broadcaster: CC1Broadcaster;agentFocusBroadcaster: AgentFocusBroadcaster;agentPresenceBroadcaster: AgentPresenceBroadcaster;@@ -1047,6 +1055,10 @@ export function createServer(options: ServerOptions): ServerInstance {let lossRing: LossCaptureRing | undefined;let hocuspocus: Hocuspocus;let sessionManager: AgentSessionManager;+ // Natively-routed /api/* groups exposed by the api extension; handed to+ // `mountMcpAndApi` (and the Vite dev plugin) so the Hono app can claim the+ // ported paths ahead of the strangler catch-all.+ let nativeApi: NativeApiHandle;// Set at boot when the loss detector is enabled; shared by the agent-session// manager (agent-undo) and the file-watcher intake path (dirty-open-doc).let bridgeLossReporter: BridgeDeriveLossReporter | undefined;@@ -1940,6 +1952,7 @@ export function createServer(options: ServerOptions): ServerInstance {},});hocuspocus.configuration.extensions.push(apiExtension);+ nativeApi = apiExtension.nativeApi;// Bridge loss-hardening wiring: resolve the defer-guard kill-switch// and construct the content-free loss ring once at boot. Reading the@@ -4558,6 +4571,7 @@ export function createServer(options: ServerOptions): ServerInstance {hocuspocus,durabilityState,sessionManager,+ nativeApi,cc1Broadcaster,agentFocusBroadcaster,agentPresenceBroadcaster,