Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { spawn } from 'node:child_process';
import type { IncomingMessage, ServerResponse } from 'node:http';
import {
EmptyRequestSchema,
encodeShareUrl,
InvalidShareUrlError,
OkCliCommand,
parseCanonicalGitHubShareUrl,
ShareConstructUrlRequestSchema,
ShareConstructUrlResponseSchema,
SharePublishNameCheckResponseSchema,
SharePublishOwnersResponseSchema,
SharePublishRequestSchema,
SharePublishResponseSchema,
ShareTargetStatusRequestSchema,
ShareTargetStatusResponseSchema,
} from '@inkeep/open-knowledge-core';
import {
LOCAL_OP_PIPE_STDIO_OPTIONS,
withHiddenWindowsConsole,
} from '../child-process-windows-hide.ts';
import { isValidBranchInfoPath } from '../git-branch-info.ts';
import type { ConcurrencyGuard } from '../local-op-security.ts';
import type { PinoLogger } from '../logger.ts';
import {
buildGitHubBlobUrl,
buildGitHubTreeUrl,
emitShareConstructUrlLog,
isValidSharePath,
SHARE_BASE_URL,
SHARE_CONSTRUCT_URL_HANDLER_TAG,
} from '../share/construct-url.ts';
import { computeShareFreshness } from '../share/freshness.ts';
import {
branchExistsOnOrigin,
readDeclaredGitHubHosts,
readGitHeadBranch,
readOriginGitHubRepo,
} from '../share/git-context.ts';
import {
emitSharePublishLog,
isValidShareOwnerName,
isValidShareRepoName,
parseNameCheckEvent,
parseOwnersEvent,
parsePublishEvent,
pickTerminalJsonLine,
redactShareSubprocessStderr,
SHARE_PUBLISH_HANDLER_TAG,
SHARE_PUBLISH_KEY,
SHARE_PUBLISH_NAME_CHECK_HANDLER_TAG,
SHARE_PUBLISH_NAME_CHECK_KEY,
SHARE_PUBLISH_OWNERS_HANDLER_TAG,
SHARE_PUBLISH_OWNERS_KEY,
SHARE_PUBLISH_TIMEOUT_MS,
} from '../share/publish.ts';
import {
computeShareTargetStatus,
SHARE_TARGET_STATUS_HANDLER_TAG,
} from '../share/target-status.ts';
import type { SyncEngine } from '../sync-engine.ts';
import { type ApiRouteGroup, type ApiRouteRecord, createApiRouteGroup } from './api-pipeline.ts';
import { errorResponse } from './error-response.ts';
import { parseQuery } from './handler-utils.ts';
import { withValidation } from './request-validation.ts';
import { successResponse } from './success-response.ts';
export interface ShareRouteDeps {
declaredGitHubHosts?: ReadonlySet<string>;
projectDir: string | undefined;
contentDir: string;
log: PinoLogger;
checkLocalOpSecurity: (
req: IncomingMessage,
res: ServerResponse,
opts: { handler: string },
) => boolean;
localOpCliArgs: readonly string[] | undefined;
localOpGuard: ConcurrencyGuard;
getSyncEngine: (() => SyncEngine | null) | undefined;
resolveCredentialConfig: () => Promise<string[]>;
toGitRelativePath: (projectDir: string, absolutePath: string) => string | null;
}
export function createShareRoutes(deps: ShareRouteDeps): ApiRouteGroup {
const {
projectDir,
contentDir,
log,
checkLocalOpSecurity,
localOpCliArgs,
localOpGuard,
getSyncEngine,
resolveCredentialConfig,
toGitRelativePath,
} = deps;
const declaredGitHubHosts = deps.declaredGitHubHosts ?? readDeclaredGitHubHosts();
const okCli = OkCliCommand.resolve({
host: localOpCliArgs === undefined ? undefined : { cliArgs: localOpCliArgs },
});
const handleShareConstructUrl = withValidation(
ShareConstructUrlRequestSchema,
async (_req, res, body) => {
try {
if (!projectDir) {
emitShareConstructUrlLog('no-remote', { kind: body.kind });
successResponse(
res,
200,
ShareConstructUrlResponseSchema,
{ ok: false, error: 'no-remote' },
{ handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
);
return;
}
const sharePath = body.kind === 'doc' ? body.docPath : body.folderPath;
if (!isValidSharePath(sharePath, body.kind)) {
emitShareConstructUrlLog('invalid-path', { kind: body.kind });
successResponse(
res,
200,
ShareConstructUrlResponseSchema,
{ ok: false, error: 'invalid-path' },
{ handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
);
return;
}
const branch = readGitHeadBranch(projectDir);
if (branch === null) {
const originPeek = readOriginGitHubRepo(projectDir, declaredGitHubHosts);
if (originPeek.kind === 'no-remote') {
emitShareConstructUrlLog('no-remote', { kind: body.kind });
successResponse(
res,
200,
ShareConstructUrlResponseSchema,
{ ok: false, error: 'no-remote' },
{ handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
);
return;
}
emitShareConstructUrlLog('detached-head', { kind: body.kind });
successResponse(
res,
200,
ShareConstructUrlResponseSchema,
{ ok: false, error: 'detached-head' },
{ handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
);
return;
}
const origin = readOriginGitHubRepo(projectDir, declaredGitHubHosts);
if (origin.kind === 'no-remote') {
emitShareConstructUrlLog('no-remote', { kind: body.kind });
successResponse(
res,
200,
ShareConstructUrlResponseSchema,
{ ok: false, error: 'no-remote' },
{ handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
);
return;
}
if (origin.kind === 'non-github') {
emitShareConstructUrlLog('non-github-remote', { kind: body.kind });
successResponse(
res,
200,
ShareConstructUrlResponseSchema,
{ ok: false, error: 'non-github-remote' },
{ handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
);
return;
}
const branchExists = branchExistsOnOrigin(projectDir, branch);
if (!branchExists) {
emitShareConstructUrlLog('branch-not-on-origin', {
branchExists: false,
kind: body.kind,
});
successResponse(
res,
200,
ShareConstructUrlResponseSchema,
{ ok: false, error: 'branch-not-on-origin', branch },
{ handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
);
return;
}
const contentRel = toGitRelativePath(projectDir, contentDir);
if (contentRel === null) {
throw new Error('content dir is not contained within the project dir');
}
const repositorySharePath =
contentRel === ''
? sharePath
: sharePath === ''
? contentRel
: `${contentRel}/${sharePath}`;
let sharedUrl: string;
if (body.kind === 'doc') {
sharedUrl = buildGitHubBlobUrl(
origin.host,
origin.owner,
origin.repo,
branch,
repositorySharePath,
);
} else {
sharedUrl = buildGitHubTreeUrl(
origin.host,
origin.owner,
origin.repo,
branch,
repositorySharePath,
);
}
let shareUrl: string;
try {
const contentRootDepth =
contentRel === ''
? 0
: parseCanonicalGitHubShareUrl(
buildGitHubTreeUrl(origin.host, origin.owner, origin.repo, branch, contentRel),
).targetSegments.length;
shareUrl = `${SHARE_BASE_URL}${encodeShareUrl(sharedUrl, contentRootDepth)}`;
} catch (err) {
if (!(err instanceof InvalidShareUrlError)) throw err;
emitShareConstructUrlLog('unsupported-share-url', { kind: body.kind });
successResponse(
res,
200,
ShareConstructUrlResponseSchema,
{ ok: false, error: 'unsupported-share-url' },
{ handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
);
return;
}
const freshness = await computeShareFreshness(
projectDir,
branch,
repositorySharePath,
body.kind,
);
emitShareConstructUrlLog('ok', { branchExists: true, kind: body.kind, freshness });
successResponse(
res,
200,
ShareConstructUrlResponseSchema,
{ ok: true, shareUrl, sharedUrl, branch, freshness },
{ handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
);
} catch (err) {
errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
handler: SHARE_CONSTRUCT_URL_HANDLER_TAG,
cause: err,
});
}
},
{
handler: SHARE_CONSTRUCT_URL_HANDLER_TAG,
method: 'POST',
preBodyGate: (req, res) =>
checkLocalOpSecurity(req, res, { handler: SHARE_CONSTRUCT_URL_HANDLER_TAG }),
},
);
function projectRenamedShareTarget(
repositoryPath: string,
renamedRepositoryPath: string,
contentRootDepth: number,
): { verdict: 'renamed'; renamedTo: string } | { verdict: 'unknown' } {
const originalSegments = repositoryPath.split('/');
const renamedSegments = renamedRepositoryPath.split('/');
if (contentRootDepth >= originalSegments.length || contentRootDepth >= renamedSegments.length) {
return { verdict: 'unknown' };
}
for (let index = 0; index < contentRootDepth; index += 1) {
if (originalSegments[index] !== renamedSegments[index]) return { verdict: 'unknown' };
}
return { verdict: 'renamed', renamedTo: renamedSegments.slice(contentRootDepth).join('/') };
}
const handleShareTargetStatus = withValidation(
ShareTargetStatusRequestSchema,
async (_req, res, body) => {
try {
if (!projectDir) {
errorResponse(
res,
500,
'urn:ok:error:internal-server-error',
'projectDir is not configured for this server.',
{ handler: SHARE_TARGET_STATUS_HANDLER_TAG },
);
return;
}
/**
* Validate the path shape before it reaches git's `<ref>:<path>` ref-spec, mirroring the
* sibling share handlers (precedent #55 content-scope predicate symmetry).
*/
if (!isValidBranchInfoPath(body.path, body.kind)) {
errorResponse(res, 400, 'urn:ok:error:invalid-request', 'path is missing or malformed.', {
handler: SHARE_TARGET_STATUS_HANDLER_TAG,
});
return;
}
const status = await computeShareTargetStatus(
projectDir,
body.branch,
body.path,
body.kind,
{
credentialConfig: await resolveCredentialConfig(),
},
);
const contentStatus =
status.verdict !== 'renamed' || body.contentRootDepth === undefined
? status
: projectRenamedShareTarget(body.path, status.renamedTo, body.contentRootDepth);
successResponse(res, 200, ShareTargetStatusResponseSchema, contentStatus, {
handler: SHARE_TARGET_STATUS_HANDLER_TAG,
});
} catch (err) {
errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
handler: SHARE_TARGET_STATUS_HANDLER_TAG,
cause: err,
});
}
},
{
handler: SHARE_TARGET_STATUS_HANDLER_TAG,
method: 'POST',
preBodyGate: (req, res) =>
checkLocalOpSecurity(req, res, { handler: SHARE_TARGET_STATUS_HANDLER_TAG }),
},
);
async function spawnShareSubprocess(
args: readonly string[],
): Promise<{ stdout: string; code: number | null }> {
const invocation = okCli.spawn(args, process.env);
if ('refused' in invocation) throw new Error(invocation.refused);
return await new Promise<{ stdout: string; code: number | null }>((resolveSpawn, reject) => {
const child = spawn(
invocation.command,
invocation.args,
withHiddenWindowsConsole({
...LOCAL_OP_PIPE_STDIO_OPTIONS,
env: invocation.env,
}),
);
let settled = false;
const killTimer = setTimeout(() => {
if (settled) return;
settled = true;
try {
child.kill('SIGKILL');
} catch {}
child.stdout.destroy();
child.stderr.destroy();
reject(new Error(`share subprocess timed out after ${SHARE_PUBLISH_TIMEOUT_MS}ms`));
}, SHARE_PUBLISH_TIMEOUT_MS);
killTimer.unref?.();
const stdoutChunks: Buffer[] = [];
const stderrChunks: Buffer[] = [];
child.stdout.on('data', (chunk: Buffer) => stdoutChunks.push(chunk));
child.stderr.on('data', (chunk: Buffer) => stderrChunks.push(chunk));
child.on('close', (code) => {
if (settled) return;
settled = true;
clearTimeout(killTimer);
const stdout = Buffer.concat(stdoutChunks).toString('utf-8');
if (code !== 0) {
const stderr = Buffer.concat(stderrChunks).toString('utf-8');
const redacted = redactShareSubprocessStderr(stderr).slice(0, 500);
log.warn(
{ code, stderr: redacted },
`[share] subprocess exited code=${code} stderr=${redacted}`,
);
}
resolveSpawn({ stdout, code });
});
child.on('error', (err) => {
if (settled) return;
settled = true;
clearTimeout(killTimer);
reject(err);
});
});
}
const handleSharePublishOwners = withValidation(
EmptyRequestSchema,
async (_req, res) => {
if (!localOpGuard.tryAcquire(SHARE_PUBLISH_OWNERS_KEY)) {
errorResponse(
res,
429,
'urn:ok:error:concurrent-operation',
'A share owners operation is already in progress.',
{ handler: SHARE_PUBLISH_OWNERS_HANDLER_TAG, extraHeaders: { 'Retry-After': '5' } },
);
return;
}
try {
const { stdout } = await spawnShareSubprocess(['share', 'owners', '--json']);
const event = pickTerminalJsonLine(stdout);
const body = parseOwnersEvent(event);
emitSharePublishLog(
'owners-list',
body.ok ? 'ok' : body.error,
body.ok ? { count: body.owners.length } : undefined,
);
successResponse(res, 200, SharePublishOwnersResponseSchema, body, {
handler: SHARE_PUBLISH_OWNERS_HANDLER_TAG,
});
} catch (err) {
errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
handler: SHARE_PUBLISH_OWNERS_HANDLER_TAG,
cause: err,
});
} finally {
localOpGuard.release(SHARE_PUBLISH_OWNERS_KEY);
}
},
{
handler: SHARE_PUBLISH_OWNERS_HANDLER_TAG,
method: 'GET',
skipBodyParse: true,
preBodyGate: (req, res) =>
checkLocalOpSecurity(req, res, { handler: SHARE_PUBLISH_OWNERS_HANDLER_TAG }),
},
);
const handleSharePublishNameCheck = withValidation(
EmptyRequestSchema,
async (req, res) => {
const params = parseQuery(req);
const owner = params.get('owner') ?? '';
const name = params.get('name') ?? '';
if (!isValidShareOwnerName(owner) || !isValidShareRepoName(name)) {
errorResponse(
res,
400,
'urn:ok:error:invalid-request',
'owner and name query params must be valid GitHub identifiers.',
{ handler: SHARE_PUBLISH_NAME_CHECK_HANDLER_TAG },
);
return;
}
if (!localOpGuard.tryAcquire(SHARE_PUBLISH_NAME_CHECK_KEY)) {
errorResponse(
res,
429,
'urn:ok:error:concurrent-operation',
'A share name-check operation is already in progress.',
{ handler: SHARE_PUBLISH_NAME_CHECK_HANDLER_TAG, extraHeaders: { 'Retry-After': '5' } },
);
return;
}
try {
const { stdout } = await spawnShareSubprocess([
'share',
'name-check',
'--owner',
owner,
'--name',
name,
'--json',
]);
const event = pickTerminalJsonLine(stdout);
const body = parseNameCheckEvent(event);
emitSharePublishLog(
'name-check',
body.ok ? 'ok' : body.error,
body.ok ? { available: body.available } : undefined,
);
successResponse(res, 200, SharePublishNameCheckResponseSchema, body, {
handler: SHARE_PUBLISH_NAME_CHECK_HANDLER_TAG,
});
} catch (err) {
errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
handler: SHARE_PUBLISH_NAME_CHECK_HANDLER_TAG,
cause: err,
});
} finally {
localOpGuard.release(SHARE_PUBLISH_NAME_CHECK_KEY);
}
},
{
handler: SHARE_PUBLISH_NAME_CHECK_HANDLER_TAG,
method: 'GET',
skipBodyParse: true,
preBodyGate: (req, res) =>
checkLocalOpSecurity(req, res, { handler: SHARE_PUBLISH_NAME_CHECK_HANDLER_TAG }),
},
);
const handleSharePublish = withValidation(
SharePublishRequestSchema,
async (_req, res, body) => {
if (!projectDir) {
emitSharePublishLog('publish-create', 'no-project');
successResponse(
res,
200,
SharePublishResponseSchema,
{ ok: false, error: 'no-project' },
{ handler: SHARE_PUBLISH_HANDLER_TAG },
);
return;
}
if (!isValidShareOwnerName(body.owner) || !isValidShareRepoName(body.name)) {
errorResponse(
res,
400,
'urn:ok:error:invalid-request',
'owner and name must be valid GitHub identifiers.',
{ handler: SHARE_PUBLISH_HANDLER_TAG },
);
return;
}
if (!localOpGuard.tryAcquire(SHARE_PUBLISH_KEY)) {
errorResponse(
res,
429,
'urn:ok:error:concurrent-operation',
'A share publish operation is already in progress.',
{ handler: SHARE_PUBLISH_HANDLER_TAG, extraHeaders: { 'Retry-After': '5' } },
);
return;
}
try {
const args = [
'share',
'publish',
'--owner',
body.owner,
'--name',
body.name,
'--visibility',
body.visibility,
'--project-dir',
projectDir,
'--json',
];
if (body.description !== undefined && body.description.length > 0) {
args.push('--description', body.description);
}
const { stdout } = await spawnShareSubprocess(args);
const event = pickTerminalJsonLine(stdout);
const responseBody = parsePublishEvent(event);
emitSharePublishLog('publish-create', responseBody.ok ? 'ok' : responseBody.error);
if (responseBody.ok) {
void getSyncEngine?.()
?.refreshRemote()
.catch((err) => {
log.warn({ err }, '[share] post-publish refreshRemote failed');
});
}
successResponse(res, 200, SharePublishResponseSchema, responseBody, {
handler: SHARE_PUBLISH_HANDLER_TAG,
});
} catch (err) {
errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
handler: SHARE_PUBLISH_HANDLER_TAG,
cause: err,
});
} finally {
localOpGuard.release(SHARE_PUBLISH_KEY);
}
},
{
handler: SHARE_PUBLISH_HANDLER_TAG,
method: 'POST',
preBodyGate: (req, res) =>
checkLocalOpSecurity(req, res, { handler: SHARE_PUBLISH_HANDLER_TAG }),
},
);
const routes = {
'/api/share/construct-url': handleShareConstructUrl,
'/api/share/target-status': handleShareTargetStatus,
'/api/share/publish/owners': handleSharePublishOwners,
'/api/share/publish/name-check': handleSharePublishNameCheck,
'/api/share/publish': handleSharePublish,
} satisfies ApiRouteRecord;
return createApiRouteGroup(routes);
}