Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import type { IncomingMessage, ServerResponse } from 'node:http';
import {
EmptyRequestSchema,
HistorySuccessSchema,
HistoryVersionSuccessSchema,
isValidBranchName,
} from '@inkeep/open-knowledge-core';
import { getLogger, type PinoLogger } from '../logger.ts';
import {
createAncestorShaSetCache,
getOrLoadRenameLogIndex,
pendingRenameLogEntries,
resolveDocPathAtCommit,
} from '../rename-log.ts';
import { type ShadowRef, shadowGit } from '../shadow-repo.ts';
import { createSingleFlight } from '../single-flight.ts';
import { getDocumentHistory, getFolderTimeline } from '../timeline-query.ts';
import { recordTimelineCoalesced } from '../timeline-telemetry.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 HistoryRouteDeps {
contentRoot: string | undefined;
log: PinoLogger;
shadowRef: ShadowRef | undefined;
flushGitCommit: (() => Promise<void>) | undefined;
commitOkArtifactWrite: (context: string) => Promise<unknown>;
getCurrentBranch: (() => string | null) | undefined;
validateFolderRel: (
raw: string,
res: ServerResponse,
label: 'path' | 'folder',
handler: string,
components: 'ok' | 'ok-and-templates',
) => { folderRel: string; resolvedContentDir: string } | null;
safeDocPath: (docName: string, contentRoot: string) => { path: string } | { error: string };
docTreePathCandidates: (docName: string, contentRoot: string) => readonly string[];
}
export interface HistoryRoutes {
paths: readonly string[];
table: ApiRouteTable;
}
export function createHistoryRoutes(deps: HistoryRouteDeps): HistoryRoutes {
const {
contentRoot,
log,
shadowRef,
flushGitCommit,
commitOkArtifactWrite,
getCurrentBranch,
validateFolderRel,
safeDocPath,
docTreePathCandidates,
} = deps;
const historyInflight = createSingleFlight<Awaited<ReturnType<typeof getDocumentHistory>>>();
const handleHistory = withValidation(
EmptyRequestSchema,
async (req, res) => {
const shadow = shadowRef?.current;
if (!shadow) {
errorResponse(
res,
503,
'urn:ok:error:shadow-not-configured',
'Shadow repo not configured.',
{ handler: 'history' },
);
return;
}
try {
const flushStart = performance.now();
await flushGitCommit?.();
await commitOkArtifactWrite('history-read');
const flushMs = performance.now() - flushStart;
if (flushMs > 1000) {
log.warn({ durationMs: Math.round(flushMs) }, '[history] pre-read commit flush slow');
}
} catch (err) {
log.warn({ err }, '[history] pre-read commit flush failed');
}
const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
const docName = url.searchParams.get('docName') ?? '';
const folderParam = url.searchParams.get('folder');
const branch = url.searchParams.get('branch') ?? getCurrentBranch?.() ?? 'main';
if (!docName && folderParam === null) {
errorResponse(
res,
400,
'urn:ok:error:invalid-request',
'A docName or folder query parameter is required.',
{ handler: 'history' },
);
return;
}
if (!isValidBranchName(branch)) {
errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid branch name.', {
handler: 'history',
});
return;
}
if (folderParam !== null && !docName) {
const validated = validateFolderRel(folderParam, res, 'folder', 'history', 'ok');
if (!validated) return;
const rawFolderLimit = Number(url.searchParams.get('limit') ?? '50');
const folderLimit = Math.min(200, Number.isFinite(rawFolderLimit) ? rawFolderLimit : 50);
const rawFolderOffset = Number(url.searchParams.get('offset') ?? '0');
const folderOffset = Math.max(0, Number.isFinite(rawFolderOffset) ? rawFolderOffset : 0);
const folderKey = `folder\0${branch}\0${validated.folderRel}\0${folderLimit}\0${folderOffset}`;
const { promise, coalesced } = historyInflight.run(folderKey, () =>
getFolderTimeline(shadow, validated.folderRel, contentRoot ?? '.', {
branch,
limit: folderLimit,
offset: folderOffset,
}),
);
if (coalesced) recordTimelineCoalesced('folder');
const result = await promise;
successResponse(res, 200, HistorySuccessSchema, { ...result }, { handler: 'history' });
return;
}
const resolvedContentRoot = contentRoot ?? '.';
const docPathResult = safeDocPath(docName, resolvedContentRoot);
if ('error' in docPathResult) {
errorResponse(res, 400, 'urn:ok:error:invalid-request', docPathResult.error, {
handler: 'history',
});
return;
}
const rawLimit = Number(url.searchParams.get('limit') ?? '50');
const rawOffset = Number(url.searchParams.get('offset') ?? '0');
const limit = Math.min(200, Number.isFinite(rawLimit) ? rawLimit : 50);
const offset = Number.isFinite(rawOffset) ? rawOffset : 0;
const type = url.searchParams.get('type') ?? undefined;
const author = url.searchParams.get('author') ?? undefined;
const excludeAuthor = url.searchParams.get('excludeAuthor') ?? undefined;
const includeAutoCheckpoints = url.searchParams.get('includeAutoCheckpoints') === 'true';
const docKey = `doc\0${branch}\0${docName}\0${limit}\0${offset}\0${type ?? ''}\0${author ?? ''}\0${excludeAuthor ?? ''}\0${includeAutoCheckpoints ? '1' : '0'}`;
const t0 = Date.now();
try {
const { promise, coalesced } = historyInflight.run(docKey, () =>
getDocumentHistory(
shadow,
{
docName,
branch,
limit,
offset,
type,
author,
excludeAuthor,
includeAutoCheckpoints,
},
resolvedContentRoot,
),
);
if (coalesced) recordTimelineCoalesced('doc');
const result = await promise;
const duration = Date.now() - t0;
getLogger('timeline').info(
{ docName, entries: result.entries.length, durationMs: duration },
'query',
);
successResponse(res, 200, HistorySuccessSchema, { ...result }, { handler: 'history' });
} catch (e) {
errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to read history.', {
handler: 'history',
cause: e,
});
}
},
{ handler: 'history', method: 'GET', skipBodyParse: true },
);
async function handleHistoryVersion(
req: IncomingMessage,
res: ServerResponse,
sha: string,
): Promise<void> {
if (req.method !== 'GET') {
errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {
handler: 'history-version',
extraHeaders: { Allow: 'GET' },
});
return;
}
const shadow = shadowRef?.current;
if (!shadow) {
errorResponse(res, 503, 'urn:ok:error:shadow-not-configured', 'Shadow repo not configured.', {
handler: 'history-version',
});
return;
}
const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
const docName = url.searchParams.get('docName') ?? '';
const resolvedContentRoot = contentRoot ?? '.';
const pathResult = safeDocPath(docName, resolvedContentRoot);
if ('error' in pathResult) {
errorResponse(res, 400, 'urn:ok:error:invalid-request', pathResult.error, {
handler: 'history-version',
});
return;
}
const sg = shadowGit(shadow);
const branch = getCurrentBranch?.() ?? 'main';
if (!/^[0-9a-f]{40}$/i.test(sha)) {
errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid commit SHA.', {
handler: 'history-version',
});
return;
}
try {
if (pendingRenameLogEntries(getOrLoadRenameLogIndex(shadow.gitDir)).size > 0) {
await commitOkArtifactWrite('history-version-read');
}
const renameLogIndex = getOrLoadRenameLogIndex(shadow.gitDir);
const ancestorCache = createAncestorShaSetCache();
const historicalPath = await resolveDocPathAtCommit(
shadow,
docName,
sha,
branch,
renameLogIndex,
(name) => docTreePathCandidates(name, resolvedContentRoot),
ancestorCache,
);
if (historicalPath === null) {
errorResponse(
res,
404,
'urn:ok:error:doc-not-found',
'Document did not exist at this version.',
{ handler: 'history-version' },
);
return;
}
const content = await sg.raw('show', `${sha}:${historicalPath}`);
const logLine = (await sg.raw('log', '-1', '--format=%aI%x00%an', sha)).trim();
const [timestamp = '', author = ''] = logLine.split('\x00');
successResponse(
res,
200,
HistoryVersionSuccessSchema,
{ sha, content, timestamp, author },
{ handler: 'history-version' },
);
} catch (e) {
errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
handler: 'history-version',
cause: e,
});
}
}
const routes: Record<string, (req: IncomingMessage, res: ServerResponse) => Promise<void>> = {
'/api/history': handleHistory,
};
const table: ApiRouteTable = {
resolve(url) {
const handler = routes[url];
if (handler) {
return { template: url, dispatch: (req, res) => handler(req, res) };
}
if (url.startsWith('/api/history/')) {
const encodedSha = url.slice('/api/history/'.length);
return {
template: '/api/history/:sha',
dispatch: encodedSha
? async (req, res) => {
await handleHistoryVersion(req, res, decodeURIComponent(encodedSha));
}
: undefined,
};
}
return null;
},
isMutating: () => false,
};
return {
paths: [...Object.keys(routes), '/api/history/*'],
table,
};
}