Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import type { ServerResponse } from 'node:http';
import { resolve } from 'node:path';
import {
AGENT_ICON_COLORS,
type AgentWriteOutcomeFields,
colorFromSeed,
DEFAULT_LINTER_CONFIG,
FrontmatterSchemaWriteRequestSchema,
LintConfigResponseSchema,
type LinterConfig,
LintFixRequestSchema,
LintFixResultSchema,
type LintPluginFailure,
lintDocument,
MarkdownlintRuleWriteRequestSchema,
type Principal,
type ReLintFailure,
summarizeLintPluginFailures,
} from '@inkeep/open-knowledge-core';
import { ANONYMOUS_WRITER_ID, sessionWriterId } from '../agent-id.ts';
import type { AgentPresenceBroadcaster } from '../agent-presence.ts';
import {
AgentSessionCapacityError,
type AgentSessionManager,
agentWriteLossDetect,
applyAgentMarkdownWrite,
iconFromClientName,
} from '../agent-sessions.ts';
import {
type AgentWriteFlushOutcome,
answeredWithSuccessOnAppRoutes,
outcomeOfSavedWrite,
} from '../agent-write-outcome.ts';
import type { NormalizedSummary, SummaryResponse } from '../agent-write-summary.ts';
import { isConfigDoc, isSystemDoc } from '../cc1-broadcast.ts';
import type { ConflictAuthority } from '../conflict-authority.ts';
import { DocInConflictError, respondDocInConflict } from '../conflict-errors.ts';
import { recordContributor } from '../contributor-tracker.ts';
import { stripDocExtension } from '../doc-extensions.ts';
import type { StoreFailure } from '../document-durability-state.ts';
import { extractActorIdentity } from '../extract-actor-identity.ts';
import {
FrontmatterMalformedError,
respondFrontmatterMalformed,
} from '../frontmatter-malformed-error.ts';
import { assertNoSymlinkEscape, isContainmentRejection } from '../fs-safety.ts';
import { lintAndFixSource } from '../lint/audit.ts';
import {
createEmptyFrontmatterSchemaFile,
deleteFrontmatterSchemaFile,
removeFrontmatterSchemaField,
renameFrontmatterSchemaField,
type WriteFrontmatterSchemaResult,
writeFrontmatterSchemaField,
} from '../lint/frontmatter-schema-write.ts';
import { type WriteMarkdownlintResult, writeMarkdownlintRule } from '../lint/markdownlint-write.ts';
import {
composeEffectiveLinterConfig,
composeFrontmatterSchemasConfig,
resolveNativeConfigForDoc,
} from '../lint/resolve-config.ts';
import type { PinoLogger } from '../logger.ts';
import { respondAgentSessionCapacity } from './agent-session-capacity.ts';
import { type ApiRouteGroup, createApiRouteGroup } from './api-pipeline.ts';
import { errorResponse } from './error-response.ts';
import { withValidation } from './request-validation.ts';
import { successResponse } from './success-response.ts';
export interface LintWriteRouteDeps {
conflicts: Pick<ConflictAuthority, 'findByDocName'>;
contentDir: string;
projectDir: string | undefined;
signalLintConfigChanged: () => void;
getLinterBaseConfig: (() => LinterConfig) | undefined;
unmatchedGlobProblems: (effective: LinterConfig) => string[];
signalChannel: ((channel: 'files' | 'lint-config' | 'comments') => void) | undefined;
requireNonEmptyDocName: (
docName: string | undefined,
res: ServerResponse,
handler: string,
) => string | null;
resolveAlias: (docName: string) => string;
getPrincipal: (() => Principal | null) | undefined;
resolveDocFilePath: (contentDir: string, docName: string) => string | null;
summaryResponseFields: (normalized: NormalizedSummary) => {
response?: SummaryResponse;
stored: string | undefined;
};
sessionManager: AgentSessionManager;
options: {
resolveEmbed?: (basename: string, sourcePath: string) => string | null;
};
agentPresenceBroadcaster: AgentPresenceBroadcaster | undefined;
buildAgentActor: (args: {
clientName: string | undefined;
clientVersion?: string;
label?: string;
}) => {
principalId?: string;
agentType?: string;
clientName?: string;
clientVersion?: string;
label?: string;
};
flushDiskAndDetectOutcome: (docName: string) => Promise<AgentWriteFlushOutcome>;
markAgentWriteStore: (docName: string) => void;
respondPersistenceFailure: (res: ServerResponse, failure: StoreFailure, handler: string) => void;
respondStaleExternalWrite: (res: ServerResponse, handler: string, docName: string) => void;
flushDocToDisk: (docName: string, label: string) => void;
log: PinoLogger;
}
export function createLintWriteRoutes(deps: LintWriteRouteDeps): ApiRouteGroup {
const {
conflicts,
contentDir,
projectDir,
signalLintConfigChanged,
getLinterBaseConfig,
unmatchedGlobProblems,
signalChannel,
requireNonEmptyDocName,
resolveAlias,
getPrincipal,
resolveDocFilePath,
summaryResponseFields,
sessionManager,
options,
agentPresenceBroadcaster,
buildAgentActor,
flushDiskAndDetectOutcome,
markAgentWriteStore,
respondPersistenceFailure,
respondStaleExternalWrite,
flushDocToDisk,
log,
} = deps;
const handleWriteMarkdownlintRule = withValidation(
MarkdownlintRuleWriteRequestSchema,
async (_req, res, body) => {
let writeResult: WriteMarkdownlintResult;
try {
writeResult = writeMarkdownlintRule(resolve(contentDir), body.ruleId, body.value);
} catch (e) {
errorResponse(
res,
500,
'urn:ok:error:internal-server-error',
'Failed to write markdownlint config.',
{ handler: 'markdownlint-config', cause: e },
);
return;
}
if (writeResult.action === 'declined-executable') {
errorResponse(
res,
409,
'urn:ok:error:config-not-writable',
`The native markdownlint config (${writeResult.file}) is an executable module OK will not rewrite — edit it directly or convert it to JSON/JSONC/YAML.`,
{ handler: 'markdownlint-config' },
);
return;
}
signalLintConfigChanged();
try {
const base = getLinterBaseConfig?.() ?? DEFAULT_LINTER_CONFIG;
const configProblems: string[] = [];
const native = resolveNativeConfigForDoc(contentDir, undefined, (problem) =>
configProblems.push(problem),
);
const effective = composeFrontmatterSchemasConfig(
projectDir ?? contentDir,
composeEffectiveLinterConfig(base, native),
(problem) => configProblems.push(problem),
);
configProblems.push(...unmatchedGlobProblems(effective));
successResponse(
res,
200,
LintConfigResponseSchema,
{ effective, configFile: native?.file ?? null, configProblems },
{ handler: 'markdownlint-config' },
);
} catch (e) {
errorResponse(
res,
500,
'urn:ok:error:internal-server-error',
'The markdownlint rule was saved, but the effective config could not be re-read.',
{ handler: 'markdownlint-config', cause: e },
);
}
},
{ handler: 'markdownlint-config', method: 'POST' },
);
const handleWriteFrontmatterSchema = withValidation(
FrontmatterSchemaWriteRequestSchema,
async (_req, res, body) => {
let writeResult: WriteFrontmatterSchemaResult;
try {
const root = resolve(projectDir ?? contentDir);
const parentPath = body.parentPath ?? [];
writeResult = body.delete
? deleteFrontmatterSchemaFile(root, body.file)
: body.field !== undefined && body.removeField
? removeFrontmatterSchemaField(root, body.file, body.field, parentPath)
: body.field !== undefined && body.renameTo !== undefined
? renameFrontmatterSchemaField(root, body.file, body.field, body.renameTo, parentPath)
: body.field !== undefined && body.constraint !== undefined
? writeFrontmatterSchemaField(
root,
body.file,
body.field,
body.constraint,
parentPath,
)
: createEmptyFrontmatterSchemaFile(root, body.file);
} catch (e) {
errorResponse(
res,
500,
'urn:ok:error:internal-server-error',
'Failed to write the frontmatter schema.',
{ handler: 'frontmatter-schema', cause: e },
);
return;
}
if (writeResult.action === 'refused') {
errorResponse(
res,
409,
'urn:ok:error:config-not-writable',
`The frontmatter schema (${writeResult.file}) was not written: ${writeResult.reason}.`,
{ handler: 'frontmatter-schema' },
);
return;
}
if (writeResult.action === 'created' || writeResult.action === 'deleted') {
signalChannel?.('files');
}
signalLintConfigChanged();
try {
const base = getLinterBaseConfig?.() ?? DEFAULT_LINTER_CONFIG;
const configProblems: string[] = [];
const native = resolveNativeConfigForDoc(contentDir, undefined, (problem) =>
configProblems.push(problem),
);
const effective = composeFrontmatterSchemasConfig(
projectDir ?? contentDir,
composeEffectiveLinterConfig(base, native),
(problem) => configProblems.push(problem),
);
configProblems.push(...unmatchedGlobProblems(effective));
successResponse(
res,
200,
LintConfigResponseSchema,
{ effective, configFile: native?.file ?? null, configProblems },
{ handler: 'frontmatter-schema' },
);
} catch (e) {
errorResponse(
res,
500,
'urn:ok:error:internal-server-error',
'The schema was saved, but the effective config could not be re-read.',
{ handler: 'frontmatter-schema', cause: e },
);
}
},
{ handler: 'frontmatter-schema', method: 'POST' },
);
const handleLintFix = withValidation(
LintFixRequestSchema,
async (_req, res, body) => {
try {
const effectiveDocName = requireNonEmptyDocName(body.docName, res, 'lint-fix');
if (effectiveDocName === null) return;
const resolvedDocName = resolveAlias(effectiveDocName);
const actor = extractActorIdentity(
body as unknown as Record<string, unknown>,
getPrincipal,
);
if (actor.kind === 'invalid-summary') {
errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {
handler: 'lint-fix',
});
return;
}
const agentId = actor.kind === 'anonymous' ? ANONYMOUS_WRITER_ID : actor.writerId;
const agentName = actor.kind === 'anonymous' ? 'Anonymous' : actor.displayName;
const colorSeed = actor.kind === 'anonymous' ? agentId : actor.colorSeed;
const clientName = actor.kind === 'agent' ? actor.clientName : undefined;
if (isSystemDoc(resolvedDocName) || isConfigDoc(resolvedDocName)) {
errorResponse(
res,
400,
'urn:ok:error:reserved-doc-name',
`'${resolvedDocName}' is a reserved document name.`,
{ handler: 'lint-fix' },
);
return;
}
const docRelPath = resolveDocFilePath(contentDir, resolvedDocName);
if (docRelPath === null) {
errorResponse(res, 404, 'urn:ok:error:doc-not-found', 'Document not found.', {
handler: 'lint-fix',
});
return;
}
assertNoSymlinkEscape(resolve(contentDir, docRelPath), contentDir);
const baseConfig = getLinterBaseConfig?.() ?? DEFAULT_LINTER_CONFIG;
const { stored: storedSummary } = summaryResponseFields(actor.summary);
await sessionManager.withSessions(async (getSession) => {
const session = await getSession(resolvedDocName, agentId, {
displayName: agentName,
colorSeed,
clientName,
});
const source = session.dc.document.getText('source').toString();
const configWarnings: string[] = [];
const { cfg, before, fixed, ran, failures } = await lintAndFixSource({
projectDir: projectDir ?? contentDir,
contentDir,
baseConfig,
docRelPath,
source,
onConfigProblem: (problem) => configWarnings.push(problem),
});
let after = before;
let reLintFailure: ReLintFailure | undefined;
let fixOutcome: AgentWriteOutcomeFields | undefined;
const reLintFailures: LintPluginFailure[] = [];
if (fixed !== source) {
try {
const icon = iconFromClientName(clientName);
const color = AGENT_ICON_COLORS[icon] ?? colorFromSeed(colorSeed ?? agentId);
agentPresenceBroadcaster?.setPresence(agentId, {
displayName: agentName,
icon,
color,
currentDoc: resolvedDocName,
mode: 'writing',
ts: Date.now(),
});
const suppliedWriterId = sessionWriterId(session);
session.dc.document.transact(() => {
applyAgentMarkdownWrite(
session.dc.document,
fixed,
'patch',
options.resolveEmbed
? { resolveEmbed: options.resolveEmbed, sourcePath: resolvedDocName }
: undefined,
undefined,
agentWriteLossDetect(session),
suppliedWriterId,
);
}, session.origin);
markAgentWriteStore(resolvedDocName);
if (actor.kind !== 'anonymous') {
recordContributor(
resolvedDocName,
agentId,
agentName,
colorSeed,
undefined,
actor.kind === 'agent'
? buildAgentActor({
clientName: actor.clientName,
clientVersion: actor.clientVersion,
label: actor.label,
})
: actor.actor,
storedSummary,
);
}
} finally {
agentPresenceBroadcaster?.touchMode(agentId, 'idle');
}
const flushOutcome = await flushDiskAndDetectOutcome(resolvedDocName);
fixOutcome = outcomeOfSavedWrite(undefined, flushOutcome);
if (
flushOutcome?.kind === 'failure' &&
!answeredWithSuccessOnAppRoutes(flushOutcome.failure)
) {
respondPersistenceFailure(res, flushOutcome.failure, 'lint-fix');
return;
}
if (flushOutcome?.kind === 'stale-external-write') {
respondStaleExternalWrite(res, 'lint-fix', resolvedDocName);
return;
}
flushDocToDisk(resolvedDocName, 'lint-fix');
try {
after = await lintDocument(
session.dc.document.getText('source').toString(),
cfg,
docRelPath,
(failure) => reLintFailures.push(failure),
);
} catch (relintErr) {
const relintMessage =
relintErr instanceof Error ? relintErr.message : String(relintErr);
reLintFailure = {
reason: 're-lint-threw',
message:
relintMessage.trim().length > 0
? relintMessage
: `${relintErr instanceof Error ? relintErr.name : 'non-Error value'} thrown with no message`,
};
log.warn(
{ err: relintErr, handler: 'lint-fix', doc: resolvedDocName, agentId },
'post-write re-lint failed; reporting pre-fix diagnostics',
);
after = before;
}
}
const blindBeforeFix = new Set(
failures.filter((f) => f.phase === 'lint').map((f) => f.source),
);
const blindOnlyAfterFix = [
...new Set(
reLintFailures
.filter((f) => f.phase === 'lint' && !blindBeforeFix.has(f.source))
.map((f) => f.source),
),
];
if (reLintFailure === undefined && blindOnlyAfterFix.length > 0) {
reLintFailure = {
reason: 'source-went-blind',
message: `${blindOnlyAfterFix.join(', ')} linted the pre-fix text and failed on the post-fix text, so the re-lint is short their diagnostics and cannot be compared against the pre-fix run`,
};
log.warn(
{ handler: 'lint-fix', doc: resolvedDocName, agentId, sources: blindOnlyAfterFix },
'post-write re-lint lost a source that linted before the fix; reporting pre-fix diagnostics',
);
after = before;
}
const errorCount = after.filter((d) => d.severity === 'error').length;
const warningCount = after.length - errorCount;
const comparable = (d: (typeof before)[number]) => !blindBeforeFix.has(d.source);
const fixedCount = Math.max(
0,
before.filter(comparable).length - after.filter(comparable).length,
);
const responseWarnings = [
...configWarnings,
...summarizeLintPluginFailures([...failures, ...reLintFailures]),
];
successResponse(
res,
200,
LintFixResultSchema,
{
...fixOutcome,
file: docRelPath,
fixedCount,
diagnostics: after,
errorCount,
warningCount,
ran,
...(responseWarnings.length > 0 ? { warnings: responseWarnings } : {}),
...(reLintFailure ? { diagnosticsArePreFix: true, reLintFailure } : {}),
},
{ handler: 'lint-fix' },
);
});
} catch (e) {
if (isContainmentRejection(e)) {
errorResponse(res, 400, 'urn:ok:error:path-escape', 'Path escape detected.', {
handler: 'lint-fix',
});
return;
}
if (e instanceof DocInConflictError) {
respondDocInConflict(
res,
e,
'lint-fix',
conflicts.findByDocName(stripDocExtension(e.file)),
);
return;
}
if (e instanceof FrontmatterMalformedError) {
respondFrontmatterMalformed(res, e, 'lint-fix');
return;
}
if (e instanceof AgentSessionCapacityError) {
respondAgentSessionCapacity(res, e, 'lint-fix');
return;
}
log.error({ err: e }, '[lint-fix] handler failed');
errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to fix document.', {
handler: 'lint-fix',
cause: e,
});
}
},
{ handler: 'lint-fix', method: 'POST' },
);
return createApiRouteGroup(
{
'/api/lint/markdownlint-config': handleWriteMarkdownlintRule,
'/api/lint/frontmatter-schema': handleWriteFrontmatterSchema,
'/api/lint/fix': handleLintFix,
},
{
mutating: ['/api/lint/markdownlint-config', '/api/lint/frontmatter-schema', '/api/lint/fix'],
},
);
}