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 group 4 read routes native (PRD-8339) (#3922)
omar-inkeep07715105072f
diff --git a/packages/app/tests/integration/attribution-sweep-coverage.test.ts b/packages/app/tests/integration/attribution-sweep-coverage.test.tsindex 014edbf68..93040288f 100644--- a/packages/app/tests/integration/attribution-sweep-coverage.test.ts+++ b/packages/app/tests/integration/attribution-sweep-coverage.test.ts@@ -31,6 +31,10 @@ const HANDLER_SOURCES = ['http/link-graph-routes.ts','http/metrics-routes.ts','http/document-routes.ts',+ 'http/config-system-routes.ts',+ 'http/lint-routes.ts',+ 'http/history-routes.ts',+ 'http/skills-read-routes.ts',].map((file) => readFileSync(join(import.meta.dirname, '../../../server/src', file), 'utf8')),];const ACTOR_HELPER_PATH = join(diff --git a/packages/app/tests/integration/conflict-gate-coverage.test.ts b/packages/app/tests/integration/conflict-gate-coverage.test.tsindex 1ee0ba50a..90032cb4c 100644--- a/packages/app/tests/integration/conflict-gate-coverage.test.ts+++ b/packages/app/tests/integration/conflict-gate-coverage.test.ts@@ -40,6 +40,10 @@ const HANDLER_SOURCES = ['http/link-graph-routes.ts','http/metrics-routes.ts','http/document-routes.ts',+ 'http/config-system-routes.ts',+ 'http/lint-routes.ts',+ 'http/history-routes.ts',+ 'http/skills-read-routes.ts',].map((file) => readFileSync(join(import.meta.dirname, '../../../server/src', file), 'utf8')),];diff --git a/packages/app/tests/integration/error-envelope-coverage.test.ts b/packages/app/tests/integration/error-envelope-coverage.test.tsindex c1b0a5c66..e08d35120 100644--- a/packages/app/tests/integration/error-envelope-coverage.test.ts+++ b/packages/app/tests/integration/error-envelope-coverage.test.ts@@ -34,13 +34,41 @@ const HANDLER_SOURCES = ['http/link-graph-routes.ts','http/metrics-routes.ts','http/document-routes.ts',+ 'http/config-system-routes.ts',+ 'http/lint-routes.ts',+ 'http/history-routes.ts',+ 'http/skills-read-routes.ts',].map((file) => ({file,text: readFileSync(join(SERVER_SRC, file), 'utf8'),}));-/** The route table and the shared success spine live in `api-extension.ts` only. */+/** The shared success spine lives in `api-extension.ts` only (fallback owner+ * for `extractHandlerBody`). Route-table records, by contrast, now live in+ * `api-extension.ts` AND each native group file — see+ * `extractRouteTableHandlerNames`. */const source = HANDLER_SOURCES[0]?.text ?? '';+/**+ * Every `'/api/…': handle<X>` binding across all handler sources — the legacy+ * dispatch record in `api-extension.ts` AND each native group's own `const+ * routes:` record. Mirrors `attribution-sweep-coverage.test.ts` /+ * `conflict-gate-coverage.test.ts`'s `extractStaticRouteHandlerNames`: bound+ * each record on the `if (enableTestRoutes)` block (api-extension) or the+ * group file's `const table` so the table's `resolve`/`dispatch` bindings are+ * not scooped up.+ */+function extractRouteTableHandlerNames(): string[] {+ 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)].flatMap((m) => (m[1] ? [m[1]] : []));+ });+}+function listAllHandlers(): string[] {// Handlers in `api-extension.ts` come in three shapes:// (1) Legacy `async function handleX(...)` (read-only routes).@@ -231,9 +259,7 @@ describe('error envelope coverage (FR17, D36 a) — fail-on-any-occurrence', ()// The route-table block is the single source of truth for which// handlers are HTTP-reachable; the meta-test's job is only valuable// if every reachable handler is scanned.- const routeTableHandlerNames = [...source.matchAll(/'\/api\/[^']*':\s+(handle\w+),?$/gm)].map(- (m) => m[1],- );+ const routeTableHandlerNames = extractRouteTableHandlerNames();expect(routeTableHandlerNames.length).toBeGreaterThan(0);const discovered = new Set(listAllHandlers());const missingFromDiscovery = routeTableHandlerNames.filter(diff --git a/packages/server/src/api-config-system-composition.test.ts b/packages/server/src/api-config-system-composition.test.tsnew file mode 100644index 000000000..d50aa5dec--- /dev/null+++ b/packages/server/src/api-config-system-composition.test.ts@@ -0,0 +1,276 @@+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,+ makeCaptureRes,+ makeSyntheticReq,+} from './composition-rig.test-helper.ts';+import {+ type ConfigSystemRouteDeps,+ createConfigSystemRoutes,+} from './http/config-system-routes.ts';+import { checkLocalOpSecurity } from './local-op-security.ts';+import type { PinoLogger } from './logger.ts';++/**+ * Characterization: the natively-routed config + server-info read group.+ *+ * Two layers of proof, deliberately separated:+ *+ * 1. COMPOSED (booted rig): each route serves over a real socket through the+ * multi-group `nativeApi` composition — the earlier groups' tables decline+ * these URLs and the chain falls through here. These pins prove native+ * registration and the read bodies; they do NOT re-assert the shared `/api/*`+ * admission gates (foreign Origin, CORS, OPTIONS, forwarding, rebound Host),+ * which `api-admission-composition.test.ts` owns — the pipeline applies them+ * to every route, ported or not, so re-pinning them here would discriminate+ * the pipeline, not this group.+ *+ * 2. HANDLER-LEVEL (no server): the inline loopback + Host / local-op gates+ * live in the handler bodies, but the shared `/api/*` pipeline applies the+ * same predicates before it dispatches any route, so no HTTP-level test can+ * isolate them. The only layer where they are observable is the handler+ * itself — reached by dispatching through the group's `table` directly,+ * bypassing the pipeline. Those pins are what prove the inline gate survived+ * the lift.+ */++const noopLog = {+ warn() {},+ error() {},+ debug() {},+ info() {},+ trace() {},+ fatal() {},+} as unknown as PinoLogger;++/**+ * Build the config-system group with stub deps for the handler-level gate+ * pins. `isRoutePeerAdmitted` / `isAllowedWorkspaceHostHeader` are the Host+ * gate's predicates (a realistic stub — the handler's own 403 is what the pin+ * observes); `checkLocalOpSecurity` is the REAL exported gate so the local-op+ * pin asserts its genuine URN + title, not a stub's.+ */+function buildConfigSystemRoutes(overrides: Partial<ConfigSystemRouteDeps> = {}) {+ return createConfigSystemRoutes({+ contentDir: '/tmp/ok-config-system-unit',+ projectDir: undefined,+ ephemeral: false,+ log: noopLog,+ ready: undefined,+ durabilityState: { getActiveBranch: () => 'main' },+ serverInstanceId: 'test-instance',+ getDiskAckSVs: undefined,+ getCollabClientCount: undefined,+ getConfigDiagnostics: undefined,+ acpRegistry: undefined,+ loadAcpCustomAgents: undefined,+ acpHarnessAvailability: (async () => ({})) as ConfigSystemRouteDeps['acpHarnessAvailability'],+ isRoutePeerAdmitted: () => true,+ isAllowedWorkspaceHostHeader: (host) => host === '127.0.0.1',+ checkLocalOpSecurity,+ getPrincipal: undefined,+ semanticSearch: undefined,+ readSemanticProviderConfig: undefined,+ embeddingsSecretsFile: undefined,+ getFileIndex: () => new Map(),+ shadowRef: undefined,+ getCurrentBranch: undefined,+ installedAgentsCache: {+ probeAll: (async () => ({})) as ConfigSystemRouteDeps['installedAgentsCache']['probeAll'],+ },+ ...overrides,+ });+}++async function dispatch(+ group: ReturnType<typeof createConfigSystemRoutes>,+ path: string,+ reqOpts: Parameters<typeof makeSyntheticReq>[0],+): Promise<{ status: number; body: { type?: string; title?: string }; allow: unknown }> {+ const resolved = group.table.resolve(path);+ if (!resolved?.dispatch) throw new Error(`no dispatch for ${path}`);+ const req = makeSyntheticReq({ url: path, ...reqOpts });+ const { res, captured } = makeCaptureRes();+ await resolved.dispatch(req, res);+ return {+ status: captured.status,+ body: captured.body ? (JSON.parse(captured.body) as { type?: string; title?: string }) : {},+ allow: captured.headers.allow,+ };+}++/** GET routes that serve a 200 read over the booted rig (no live egress / subprocess / real $HOME). */+const READ_200 = [+ '/api/config',+ '/api/config/diagnostics',+ '/api/server-info',+ '/api/semantic-status',+ '/api/workspace',+ '/api/rescue',+ '/api/__embed-detect',+];++/** Every route in the group — method-gated, so a POST answers 405 when registered. */+const ALL_ROUTES = [...READ_200, '/api/acp/catalog', '/api/installed-agents', '/api/principal'];++let tmpRoot: string;+let server: BootedServer;++beforeAll(async () => {+ tmpRoot = await mkdtemp(resolve(tmpdir(), 'ok-config-system-native-'));+ const contentDir = mkdtempSync(resolve(tmpRoot, 'content-'));+ writeFileSync(resolve(contentDir, 'alpha.md'), '# Alpha\n\nBody.\n', 'utf-8');+ server = await bootCompositionRig(contentDir);+ await server.ready;+}, 60_000);++afterAll(async () => {+ await server?.destroy();+ await rm(tmpRoot, { recursive: true, force: true });+});++describe('config-system group over the composed listener — served natively', () => {+ test('every route in the group is registered natively (POST → 405 + Allow: GET)', async () => {+ // A native `fetch` from 127.0.0.1 carries a loopback Host and no Origin, so+ // the gated routes pass their loopback + Host gate and reach the method+ // check. An unregistered path would return the pipeline's generic+ // `/api/*` 404 instead of a 405.+ for (const path of ALL_ROUTES) {+ const res = await fetch(`http://127.0.0.1:${server.port}${path}`, { method: 'POST' });+ expect(res.status, path).toBe(405);+ expect(res.headers.get('allow'), path).toContain('GET');+ }+ });++ test('every read serves a 200 body natively (application/json + x-request-id)', async () => {+ for (const path of READ_200) {+ const res = await fetch(`http://127.0.0.1:${server.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('HEAD on the config endpoints answers 200 with headers and no body', async () => {+ // `config` and `config/diagnostics` are the only two handlers in this+ // group that answer HEAD (a no-body 200 carrying the same headers as GET);+ // pin it so the manual HEAD emit survives the lift.+ for (const path of ['/api/config', '/api/config/diagnostics']) {+ const res = await fetch(`http://127.0.0.1:${server.port}${path}`, { method: 'HEAD' });+ expect(res.status, path).toBe(200);+ expect(res.headers.get('content-type'), path).toBe('application/json');+ expect(res.headers.get('cache-control'), path).toBe('no-store');+ expect(await res.text(), path).toBe('');+ }+ });++ test('acp/catalog serves natively without depending on live CDN egress (200 or 502)', async () => {+ // The rig wires an `AcpRegistry` with no `fetchImpl` and a cold cache, so+ // the handler either serves an offline catalog (200) or emits its own+ // `502 registry-unreachable` when the CDN is unreachable — either proves+ // native serving without banking a network-dependent 200 on the required+ // `pnpm check` path. (A fixture `fetchImpl` seam for a deterministic 200 is+ // a follow-up, noted in the PR body.)+ const res = await fetch(`http://127.0.0.1:${server.port}/api/acp/catalog`);+ expect([200, 502]).toContain(res.status);+ });++ test('principal serves natively behind its inline gate (200 when resolvable, else its own 404)', async () => {+ // A native fetch passes the loopback + Host gate. Whether a principal+ // resolves depends on the host's git identity, so the pin accepts either+ // the 200 body or the handler's OWN 404 — never the pipeline route-miss.+ const res = await fetch(`http://127.0.0.1:${server.port}/api/principal`);+ expect([200, 404]).toContain(res.status);+ if (res.status === 404) {+ expect(((await res.json()) as { type?: string }).type).toBe(+ 'urn:ok:error:principal-not-available',+ );+ }+ });++ test('both chained groups answer on one server (multi-group dispatch)', async () => {+ // The link/graph group resolves first in the chain; this group only+ // answers after the earlier groups decline. One server, both arms live.+ const linkGraph = await fetch(`http://127.0.0.1:${server.port}/api/backlinks?docName=alpha`);+ expect(linkGraph.status).toBe(200);+ const config = await fetch(`http://127.0.0.1:${server.port}/api/config`);+ expect(config.status).toBe(200);+ });+});++describe('config-system inline gates — observable only at the handler layer', () => {+ test('the Host-gated reads emit a handler-owned 403 on a hostile Host', async () => {+ for (const path of ['/api/principal', '/api/workspace', '/api/__embed-detect']) {+ const out = await dispatch(buildConfigSystemRoutes(), path, { host: 'evil.example' });+ expect(out.status, path).toBe(403);+ expect(out.body.type, path).toBe('urn:ok:error:host-not-allowed');+ }+ });++ test('the Host-gated reads emit a handler-owned 403 when the peer is not admitted', async () => {+ // The peer arm of the two-arm inline gate: a good Host but a non-admitted+ // peer address must still refuse (loopback-required), before method dispatch.+ for (const path of ['/api/principal', '/api/workspace', '/api/__embed-detect']) {+ const out = await dispatch(+ buildConfigSystemRoutes({ isRoutePeerAdmitted: () => false }),+ path,+ {+ host: '127.0.0.1',+ },+ );+ expect(out.status, path).toBe(403);+ expect(out.body.type, path).toBe('urn:ok:error:loopback-required');+ }+ });++ test('the inline Host gate fires BEFORE method dispatch (POST + hostile Host → 403, no Allow)', async () => {+ for (const path of ['/api/principal', '/api/workspace', '/api/__embed-detect']) {+ const out = await dispatch(buildConfigSystemRoutes(), path, {+ method: 'POST',+ host: 'evil.example',+ });+ expect(out.status, path).toBe(403);+ expect(out.body.type, path).toBe('urn:ok:error:host-not-allowed');+ expect(out.allow, path).toBeUndefined();+ }+ });++ test('installed-agents short-circuits on checkLocalOpSecurity (foreign Origin → its own invalid-origin)', async () => {+ // Driven through the REAL `checkLocalOpSecurity` (not a stub): a loopback+ // peer with a foreign Origin passes the peer check and fails the origin+ // check, so the gate emits its OWN title — distinct from the pipeline's+ // `'Origin not allowed.'`. Only observable here, since the pipeline's+ // origin gate would answer first over HTTP. The probe counter proves the+ // gate refuses BEFORE the handler does any OS-probe work.+ let probes = 0;+ const group = buildConfigSystemRoutes({+ installedAgentsCache: {+ probeAll: (async () => {+ probes += 1;+ return {};+ }) as ConfigSystemRouteDeps['installedAgentsCache']['probeAll'],+ },+ });+ const out = await dispatch(group, '/api/installed-agents', {+ remoteAddress: '127.0.0.1',+ origin: 'https://evil.example.com',+ });+ expect(out.status).toBe(403);+ expect(out.body.type).toBe('urn:ok:error:invalid-origin');+ expect(out.body.title).toBe('Origin header is not a permitted loopback origin.');+ expect(probes).toBe(0);+ });++ test('HEAD reaches the config handler through direct dispatch (statusCode fallback surfaces 200)', async () => {+ // handleApiConfig's HEAD branch sets res.statusCode directly (no writeHead),+ // so this pin passes only because makeCaptureRes carries the statusCode+ // fallback — the one construct no other pin here exercises.+ const out = await dispatch(buildConfigSystemRoutes(), '/api/config', { method: 'HEAD' });+ expect(out.status).toBe(200);+ });+});diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.tsindex f5be8384b..d5f9a2493 100644--- a/packages/server/src/api-extension.ts+++ b/packages/server/src/api-extension.ts@@ -47,7 +47,6 @@ import {AgentWriteMdSuccessSchema,AgentWriteRequestSchema,AgentWriteSuccessSchema,- ApiConfigSuccessSchema,applyPatchToFm,type BatchEntryError,BranchInfoResponseSchema,@@ -56,9 +55,7 @@ import {ClientLogsRequestSchema,ClientLogsSuccessSchema,CONFIG_DOC_NAME_OKIGNORE,- CommentCountsSuccessSchema,type ConfigDiagnosticsReport,- ConfigDiagnosticsReportSchema,CreateFolderRequestSchema,CreateFolderSuccessSchema,CreatePageRequestSchema,@@ -80,7 +77,6 @@ import {detectFmRegion,EDITOR_PROJECT_SKILL_ROOT,type EditorId,- EmbedDetectSuccessSchema,EmptyRequestSchema,encodeShareUrl,estimateSkillCost,@@ -90,33 +86,24 @@ import {FolderConfigPutSuccessSchema,FrontmatterPatchRequestSchema,FrontmatterPatchSuccessSchema,- FrontmatterSchemasListSuccessSchema,FrontmatterSchemaWriteRequestSchema,type GitWorktreeOpenTarget,GitWorktreeStatusSuccessSchema,type HeadingEntry,- HistorySuccessSchema,- HistoryVersionSuccessSchema,type InlineAssetMediaKind,InstallSkillRequestSchema,InstallSkillSuccessSchema,InvalidShareUrlError,instantiateDoc,- isDetectedSkillInProject,- isFrontmatterSchemaAsset,- isHiddenDocName,isManagedArtifactDocName,isOpenKnowledgeSkillsSource,isSkillInstallTarget,- isSkillOutsideOpenProject,LEGACY_SKILL_STORE_ROOT,LINKABLE_ASSET_EXTENSIONS,LinkPreviewRequestSchema,LinkPreviewResponseSchema,type LinksValidationSetting,- LintAuditResponseSchema,LintConfigResponseSchema,- LintDocResultSchema,type LinterConfig,LintFixRequestSchema,LintFixResultSchema,@@ -147,7 +134,6 @@ import {OPENKNOWLEDGE_SKILLS_REPO,PROJECT_SKILL_EDITOR_IDS,type Principal,- PrincipalSuccessSchema,type ProblemType,parseCanonicalGitHubShareUrl,parseFrontmatterRecord,@@ -157,9 +143,6 @@ import {RENAMED_PACK_SKILLS,RenamePathRequestSchema,RenamePathSuccessSchema,- type RescueEntryFlat,- type RescueEntryTimeline,- RescueListSuccessSchema,RollbackRequestSchema,RollbackSuccessSchema,readFmMap,@@ -180,8 +163,6 @@ import {SeedInstallPackSkillSuccessSchema,SeedListPacksSuccessSchema,SeedPlanSuccessSchema,- SemanticIndexStatusSchema,- ServerInfoSuccessSchema,ShareConstructUrlRequestSchema,ShareConstructUrlResponseSchema,SharePublishNameCheckResponseSchema,@@ -207,7 +188,6 @@ import {SkillImportRequestSchema,SkillImportSuccessSchema,SkillInstallRequestSchema,- SkillInstallStateSuccessSchema,SkillInstallSuccessSchema,type SkillInstallWarningCode,SkillMoveRequestSchema,@@ -226,7 +206,6 @@ import {SkillScopeSchema,SkillsImportBulkRequestSchema,SkillsImportBulkSuccessSchema,- SkillsInstalledSuccessSchema,SkillsListSuccessSchema,SkillsReimportBulkRequestSchema,SkillsReimportBulkSuccessSchema,@@ -260,7 +239,6 @@ import {TemplateMoveSuccessSchema,TemplatePutRequestSchema,TemplatePutSuccessSchema,- TemplatesListSuccessSchema,TestFlushGitSuccessSchema,TestRescanBacklinksSuccessSchema,TestRescanFilesSuccessSchema,@@ -272,13 +250,10 @@ import {UploadRequestSchema,USER_SKILL_EDITOR_IDS,unwrapFrontmatterFences,- ValidationAuditCountsResponseSchema,- ValidationAuditResponseSchema,type ValidationDiagnostic,type WorkspaceSearchIntent,type WorkspaceSearchRanking,type WorkspaceSearchScope,- WorkspaceSuccessSchema,} from '@inkeep/open-knowledge-core';import {formatRenameSubject,@@ -314,17 +289,10 @@ import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';import { type Entry, fromBuffer as yauzlFromBuffer, type ZipFile } from 'yauzl';import { z } from 'zod';import {- ACP_AGENT_HARNESS_CLIS,type AcpHarnessAvailability,createAcpHarnessAvailabilityProbe,} from './acp/harness-availability.ts';-import {- type AcpRegistry,- type CustomAgentEntry,- FEATURED_AGENT_IDS,- registryPlatformKey,-} from './acp/registry.ts';-import { MAX_ACP_THREADS } from './acp/thread-manager.ts';+import type { AcpRegistry, CustomAgentEntry } from './acp/registry.ts';import { captureEffect } from './activity-log.ts';import { listAgentActivity, synthesizeVersionDiff } from './agent-activity.ts';import type { AgentFocusBroadcaster } from './agent-focus.ts';@@ -344,7 +312,6 @@ import {} from './agent-sessions.ts';import { type NormalizedSummary, normalizeSummary } from './agent-write-summary.ts';import { resolveBundledSkillDir } from './build-skill-zip.ts';-import { collabUrlFromRequestHeaders } from './collab-bootstrap-url.ts';import { createCommentApi } from './comments/comment-api.ts';import { CommentIndex } from './comments/comment-index.ts';import { CommentService } from './comments/comment-service.ts';@@ -367,10 +334,7 @@ import {countBundleFiles,} from './content/skills-write.ts';import { applySubstitution, todayIsoUtc } from './content/substitution.ts';-import {- resolveProjectTemplates,- resolveTemplatesAvailable,-} from './content/templates-resolver.ts';+import { resolveTemplatesAvailable } from './content/templates-resolver.ts';import {applyTemplateDelete,applyTemplateMove,@@ -383,7 +347,6 @@ import {toContentDivergenceWarning,} from './content-divergence-gate.ts';import { recordContributor } from './contributor-tracker.ts';-import { deriveDetection, embedProbeRing } from './embed-probe.ts';import {FileEmbeddingsBackend,probeEmbeddingEndpoint,@@ -401,7 +364,6 @@ import { assertNoSymlinkEscape } from './fs-safety.ts';import {createInstalledAgentsProbe,createOsProbe,- handleInstalledAgents,type InstalledAgentScheme,} from './handoff-api.ts';import { handleHandoffDispatch } from './handoff-dispatch-api.ts';@@ -411,14 +373,7 @@ import {recordSkillInstall,removeSkillInstall,} from './installed-skills-marker.ts';-import {- AuditSupersededError,- auditProject,- collectDocFiles,- lintAndFixSource,- lintDoc,-} from './lint/audit.ts';-import { AuditCache } from './lint/audit-cache.ts';+import { collectDocFiles, lintAndFixSource } from './lint/audit.ts';import {createEmptyFrontmatterSchemaFile,deleteFrontmatterSchemaFile,@@ -427,11 +382,7 @@ import {type WriteFrontmatterSchemaResult,writeFrontmatterSchemaField,} from './lint/frontmatter-schema-write.ts';-import {- listProjectSchemaFiles,- SCHEMA_LIST_CAP,- unmatchedAppliesToProblems,-} from './lint/frontmatter-schemas.ts';+import { unmatchedAppliesToProblems } from './lint/frontmatter-schemas.ts';import { type WriteMarkdownlintResult, writeMarkdownlintRule } from './lint/markdownlint-write.ts';import {composeEffectiveLinterConfig,@@ -439,13 +390,7 @@ import {resolveEffectiveLinterConfig,resolveNativeConfigForDoc,} from './lint/resolve-config.ts';-import {- createProjectValidators,- type ProjectValidator,- runValidationAudit,- toValidationCountsPlane,- type ValidationAuditResult,-} from './lint/validation-audit.ts';+import { createProjectValidators } from './lint/validation-audit.ts';import { validateMermaidFences } from './mermaid-validator.ts';import {extractPageTitle,@@ -455,7 +400,6 @@ import {import type { RecentlyRemovedDocs } from './recently-removed-docs.ts';import { scanSavedThemes } from './saved-themes-store.ts';import { deleteSavedTheme, saveSavedTheme, updateSavedTheme } from './saved-themes-write.ts';-import { readServerLock } from './server-lock.ts';import {buildGitHubBlobUrl,buildGitHubTreeUrl,@@ -516,7 +460,6 @@ import {validateSkillForInstall,} from './skill-projection.ts';import { rewriteSkillRefsAcrossScope, type SkillRefRewrite } from './skill-ref-rename.ts';-import { readSkillInstallStateSnapshot } from './skill-state.ts';import { handleSpawnCursor } from './spawn-cursor-api.ts';import { assertRealpathWithinDir } from './symlink-guard.ts';import { HashingPassThrough, mintTempUploadPath } from './upload-streaming.ts';@@ -553,7 +496,6 @@ import {ManagedRenameSourceTypeMismatchError,SymlinkEscapeError,} from './apply-managed-rename.ts';-import { getBootTimings } from './boot-timings.ts';import { composeAndWriteRawBody, type PrecomputedParse, replaceRawBody } from './bridge-intake.ts';import type { BridgeDeriveLossReporter } from './bridge-loss-detector.ts';import { isConfigDoc, isLinkIndexExcludedDoc, isSystemDoc } from './cc1-broadcast.ts';@@ -624,6 +566,7 @@ import { writeGitIdentity } from './git-identity.ts';import { readWorktreeStatus } from './git-worktree-status.ts';import { type ApiRouteTable, createApiRequestPipeline } from './http/api-pipeline.ts';import { catchErrors } from './http/catch-errors.ts';+import { createConfigSystemRoutes } from './http/config-system-routes.ts';import { createDocumentRoutes } from './http/document-routes.ts';import {createStreamingErrorWriter,@@ -631,13 +574,16 @@ import {type HttpErrorStatus,} from './http/error-response.ts';import { errnoCode, parseQuery } from './http/handler-utils.ts';+import { createHistoryRoutes } from './http/history-routes.ts';import { assertSingleRouterOwnership, type NativeApiHandle } from './http/http-app.ts';import { createLinkGraphRoutes } from './http/link-graph-routes.ts';+import { createLintRoutes } from './http/lint-routes.ts';import { createLocalApiDispatch, type LocalApiDispatch } from './http/local-api-dispatch.ts';import { methodRouter } from './http/method-router.ts';import { createMetricsRoutes } from './http/metrics-routes.ts';import { getRequestId } from './http/request-id.ts';import { validateBody, withValidation } from './http/request-validation.ts';+import { createSkillsReadRoutes } from './http/skills-read-routes.ts';import { successResponse } from './http/success-response.ts';import {aliasedSourceRoots,@@ -732,16 +678,13 @@ import {} from './services/skill-reimport.ts';import { createVersionOpsService } from './services/version-ops.ts';import {- listRescueCheckpoints,SERVICE_WRITER,type ShadowRef,safetyCheckpoint,shadowGit,- type TimelineRescueEntry,type WriterIdentity,} from './shadow-repo.ts';import { shouldResetAmbientCredentials } from './share/git-context.ts';-import { createSingleFlight } from './single-flight.ts';import {linkEditorSkillFolder,previewEditorFolderLink,@@ -764,8 +707,6 @@ import { createSkillsShHandlers } from './skills-sh-handlers.ts';import { reportSkillInstall } from './skills-sh-install-report.ts';import type { SyncEngine } from './sync-engine.ts';import { getMeter, withSpan, withSpanSync } from './telemetry.ts';-import { getDocumentHistory, getFolderTimeline } from './timeline-query.ts';-import { recordTimelineCoalesced } from './timeline-telemetry.ts';import { resolveUiRedirectPort } from './ui-redirect-port.ts';import { computeWriteAdvisoryLinks } from './write-advisory-links.ts';@@ -2979,12 +2920,6 @@ export function createApiExtension(// Concurrency guard: at most 1 in-flight request per local-op endpointconst localOpGuard = localOpConcurrencyGuard ?? createConcurrencyGuard();- // Single-flight dedupe for `GET /api/history`. Keyed by the- // full normalized query tuple (mode + branch + every param each mode reads),- // so N concurrent identical history requests share ONE git walk and N- // identical responses. Per-server-instance, same rationale as showAllInflight.- const historyInflight = createSingleFlight<Awaited<ReturnType<typeof getDocumentHistory>>>();-// The document/pages native route group is constructed HERE, well above the// route-table tail, because its returned `invalidateReferencedAssetsCache`// is called from the write spines below (create/delete/rename) — the same@@ -6633,151 +6568,6 @@ export function createApiExtension({ handler: 'frontmatter-patch', method: 'POST' },);- /**- * Read-only cross-harness installed-skill enumeration. `GET /api/skills/installed`- * returns `{ skills, packs }` — every skill OK can see across all harness- * homes (Claude plugins + the bare skill dirs), normalized + de-duped. Pure- * read: no home is mutated (NOT in MUTATING_ROUTES). 200 with empty arrays on- * a machine with nothing installed.- */- const handleSkillsInstalled = withValidation(- EmptyRequestSchema,- async (_req, res) => {- try {- // The catalog is machine-global; the detected sidebar shows it under the- // OPEN project's scopes. Two moves keep it faithful to the project |- // global invariant (precedent #50): (1) resolve a linked worktree to its- // parent-checkout identity so the parent's project-scoped installs- // (keyed on the parent path) still match here; (2) ALSO scan this- // project's `.<harness>/skills` dirs so every harness's project skills- // surface, not just Claude plugins. The SAME identity is used to scan,- // stamp, and filter — drop skills bound to a *different* project.- const identity = resolveProjectIdentity(projectDir ?? contentDir);- // Same `homeDirOverride` seam as every other home-scanning surface here —- // without it a rig (or embedded host) enumerates the REAL ~/.claude/plugins.- const catalog = enumerateInstalledSkillsCached({- projectDir: identity,- ...(homeDirOverride !== undefined ? { home: homeDirOverride } : {}),- });- // In-place editor-dir skills are first-class `/api/skills`- // entries at BOTH scopes — dropping them here keeps the same skill from- // double-listing as a "detected" row. What remains detected: plugin-cache- // skills (`~/.claude/plugins/**`), which the in-place scans don't cover.- const inPlaceNames = new Set(scanInPlaceSkills(contentDir).map((s) => s.name));- const globalInPlaceNames = new Set(scanGlobalInPlaceSkills(skillsHome).map((s) => s.name));- const result = {- ...catalog,- skills: catalog.skills- .filter(- (s) =>- isDetectedSkillInProject(s.provenance, identity) &&- !(s.provenance.scope === 'project'- ? inPlaceNames.has(s.name)- : globalInPlaceNames.has(s.name)),- )- // `identity` is the PARENT checkout for a linked worktree, so a skill- // can match the project while living in a tree the user does not have- // open. Stamp that so the client can refuse an in-place edit that would- // land in another checkout on another branch.- //- // The reference is the OPEN PROJECT ROOT — `projectDir ?? contentDir`,- // the same expression `identity` is derived from but WITHOUT the- // worktree→parent resolution. Not `identity` (that resolution makes the- // test vacuously false), and not `contentDir`: under `content.dir: docs`- // contentDir is `<projectDir>/docs` while harness skill dirs sit at- // `<projectDir>/.codex/skills/…`, so every project skill in the user's- // OWN checkout would be flagged foreign.- .map((s) =>- isSkillOutsideOpenProject(s.provenance, s.home, projectDir ?? contentDir)- ? { ...s, outsideProject: true }- : s,- ),- };- successResponse(res, 200, SkillsInstalledSuccessSchema, result, {- handler: 'skills-installed',- });- } catch (e) {- errorResponse(- res,- 500,- 'urn:ok:error:internal-server-error',- 'Failed to enumerate installed skills.',- { handler: 'skills-installed', cause: e },- );- }- },- { handler: 'skills-installed', 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- * `{ counts: { a: 2, b: 0 } }`; `?prefix=folder` returns the same shape for- * every doc under that folder that carries threads (sparse — a comment-free- * subtree yields `{}`), which is how an `ls` entry gets a folder rollup- * without a request per file.- *- * Read-only, so it stays out of `MUTATING_ROUTES` — unlike `/api/comments`,- * whose POST creates threads. docNames failing `isSafeDocName` are silently- * dropped, matching backlink-counts; a malformed `prefix` is a 400 because- * dropping it would silently widen the query to the whole project.- */- const handleCommentCounts = withValidation(- EmptyRequestSchema,- async (req, res) => {- try {- const url = new URL(req.url ?? '', 'http://localhost');- const prefix = url.searchParams.get('prefix');- const raw = url.searchParams.get('docNames');- if (prefix === null && raw === null) {- errorResponse(- res,- 400,- 'urn:ok:error:invalid-request',- 'Missing docNames or prefix parameter.',- { handler: 'comment-counts' },- );- return;- }- let counts: Record<string, number> = {};- if (prefix !== null) {- const trimmed = prefix.trim();- if (trimmed !== '' && !isSafeDocName(trimmed)) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid prefix parameter.', {- handler: 'comment-counts',- });- return;- }- counts = Object.fromEntries(await commentService.countThreads({ prefix: trimmed }));- } else {- const docNames = (raw ?? '')- .split(',')- .map((name) => name.trim())- .filter((name) => name !== '' && isSafeDocName(name));- counts = Object.fromEntries(await commentService.countThreads({ docNames }));- }- successResponse(- res,- 200,- CommentCountsSuccessSchema,- { counts },- {- handler: 'comment-counts',- },- );- } catch (e) {- errorResponse(- res,- 500,- 'urn:ok:error:internal-server-error',- 'Failed to read comment counts.',- { handler: 'comment-counts', cause: e },- );- }- },- { handler: 'comment-counts', method: 'GET', skipBodyParse: true },- );-const handleAgentPatch = withValidation(AgentPatchRequestSchema,async (_req, res, body) => {@@ -7896,264 +7686,6 @@ export function createApiExtension({ handler: 'save-version', method: 'POST' },);- // ── GET /api/history ─────────────────────────────────────────────────────- const handleHistory = withValidation(- EmptyRequestSchema,- async (req, res) => {- const shadow = shadowRef?.current;- if (!shadow) {- // 503 (not 400): shadow-repo unavailability is a server-side state,- // matching the sync-not-active precedent.- errorResponse(- res,- 503,- 'urn:ok:error:shadow-not-configured',- 'Shadow repo not configured.',- { handler: 'history' },- );- return;- }-- // Read-your-writes: agent write handlers no longer force an L2 shadow- // commit per write (they ride the persistence debounce), so drain any- // pending commit before querying — a `history` call issued right after a- // write must list that write. No-op when nothing is pending. The flush- // blocks the response, so surface slow (cold-index) drains in the logs.- try {- const flushStart = performance.now();- await flushGitCommit?.();- // Contributor stragglers too: lifecycle writes flush fire-and-forget- // now, so a contributor recorded after an in-flight run snapshotted- // the map is not in the drained commit — without this second drain the- // just-made version is missing from the timeline. Reader-side on- // purpose: draining in the generic flush changed shutdown semantics.- 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 (branch.includes('..') || !/^[a-zA-Z0-9][a-zA-Z0-9._/-]*$/.test(branch)) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid branch name.', {- handler: 'history',- });- return;- }-- // Folder timeline — attributed activity over a folder's- // `.ok/` artifacts (templates + frontmatter). Distinct from the doc DAG- // walk: no rename chain, no checkpoint filter.- if (folderParam !== null && !docName) {- const validated = validateFolderRel(folderParam, res, 'folder', 'history');- 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);- // Single-flight key — folder mode. The resolved `branch` (not the raw- // param) is used so two requests on the same effective branch coalesce.- const folderKey = `folder\0${branch}\0${validated.folderRel}\0${folderLimit}\0${folderOffset}`;- // `getFolderTimeline` is self-contained: it catches its own git/IO- // errors, logs them, and returns an empty result rather than throwing —- // so a handler-level catch here would be dead code.- 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;- }-- // Validate docName before it reaches `getDocumentHistory`, which- // interpolates it into a git pathspec for `git log` / `cat-file -e`.- // Without this guard, a docName containing `..` or null bytes could- // (after git's pathspec normalization) target a path outside the- // configured content root in the shadow repo. Sibling endpoints- // (handleHistoryVersion, handleDiff, handleRollback) already gate via- // safeDocPath.- 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;- // Auto-consolidation checkpoints are hidden by default; opt-in for- // debugging / a future maintenance UI. Part of the single-flight tuple- // because it changes the result set.- const includeAutoCheckpoints = url.searchParams.get('includeAutoCheckpoints') === 'true';-- // Single-flight key — doc mode. Covers every param `getDocumentHistory`- // reads so a differing tuple never shares a wrong result.- 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) {- // Generic title — raw `e.message` can leak FS paths / library internals.- // The underlying message is forwarded to Pino via `cause` for ops triage.- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to read history.', {- handler: 'history',- cause: e,- });- }- },- { handler: 'history', method: 'GET', skipBodyParse: true },- );-- // ── GET /api/history/:sha ─────────────────────────────────────────────────- 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) {- // 503 (not 400): shadow-repo unavailability is a server-side state,- // matching the sync-not-active precedent.- 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';-- // Validate SHA format- if (!/^[0-9a-f]{40}$/i.test(sha)) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid commit SHA.', {- handler: 'history-version',- });- return;- }-- try {- // Resolve the doc's historical path at this commit by walking the- // rename chain (mirrors handleRollback + handleDiff). Without- // this, requesting a pre-rename commit's content returns 404 even- // though the timeline correctly shows the entry — the UI then falls- // back to its "Diff unavailable" / "Document did not exist" rendering.- 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}`);-- // Resolve commit metadata- 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,- });- }- }-// ── POST /api/rollback ────────────────────────────────────────────────────const handleRollback = withValidation(RollbackRequestSchema,@@ -8462,459 +7994,80 @@ export function createApiExtension({ handler: 'rollback', method: 'POST' },);- /**- * GET /api/server-info- *- * Returns `{ ok, serverInstanceId, currentBranch, currentDiskAckSVs }`.- * Called by the client's `ProviderPool` as a boot-time warmup BEFORE- * any WebSocket provider opens, so the first provider's auth token- * can carry `expectedServerInstanceId` and `expectedBranch` on the- * very first connect (avoiding one "null-claim accept → broadcast →- * populate cache → next connect claim" cycle on cold start).- *- * `currentBranch` is the late-join backstop for CC1's `branch-switched`- * stateless broadcast — disconnected clients reconnecting compare it- * against their last-observed branch and trigger `handleBranchSwitched`- * on mismatch (also surfaced as the `expectedBranch` auth-token claim,- * see `auth-token-schema.ts`). Always populated — `getActiveBranch()`- * defaults to `'main'` when git is disabled.- *- * Gated on `ready` for the same reason `handleDocumentList` is: the- * boot-time `switchReconciledBaseScope(startupBranch)` lives inside- * `initAsync` (server-factory.ts), and a renderer that fetches before- * it runs would observe this server's initial `'main'` default instead of- * the actual HEAD branch. The renderer's `current-branch-store` is- * fire-once and only updates from CC1 `branch-switched`, so a stale- * cold-start fetch sticks until a real cross-branch checkout.- *- * `currentDiskAckSVs` is the late-join backstop for the per-doc CC1- * `disk-ack` channel — same recovery shape as `currentBranch` but the- * per-doc state vector watermark used by mismatch-recycle baseline-- * selection. Omitted in dev/plugin mode (no CC1 broadcaster).- *- * Gating: protected by the global `/api/*` Origin allowlist (CSRF- * guard against cross-origin browsers). No-Origin requests (curl,- * server-to-server, LAN peers using non-browser tooling) pass through- * — the same posture as the rest of the read-side `/api/*` surface- * (`/api/documents`, `/api/document`, `/api/pages`, `/api/backlinks`).- * Disclosure shape: `serverInstanceId` is a per-process random UUID;- * `currentBranch` matches the workspace's git history; the SV map- * enumerates the same docName set as `/api/documents` plus per-- * client Lamport op counts (random clientID, no wall-clock).- * Single-user-loopback deployment model is documented in- * `server-factory.ts` near the principalAuthExtension; hosted/multi-- * tenant deployments must wrap this entire `/api/*` class with- * authentication and per-caller scoping.- */- const handleServerInfo = withValidation(+ const assetService = createAssetService({+ contentDir,+ // `isPathIgnored` rather than `isExcluded` so the sibling-asset heuristic+ // does not reject legitimate cross-directory references. Exclusion is+ // reported as not-found: the wire shape stays identical to a missing file.+ isPathIgnored: (relativePath) => contentFilter?.isPathIgnored(relativePath) ?? false,+ getAttachmentFolderPath,+ });+ const ASSET_SERVE_ERRORS = {+ 'missing-path': [400, 'urn:ok:error:invalid-request', 'Missing asset path.'],+ 'unsupported-type': [415, 'urn:ok:error:unsupported-asset-type', 'Unsupported asset type.'],+ 'not-found': [404, 'urn:ok:error:asset-not-found', 'Asset not found.'],+ 'invalid-path': [400, 'urn:ok:error:invalid-request', 'Invalid asset path.'],+ } as const;++ const handleAsset = withValidation(EmptyRequestSchema,- async (_req, res) => {+ async (req, res) => {try {- // Park until `initAsync` has called `switchReconciledBaseScope` with- // the resolved HEAD branch. Without this gate, a renderer that fetches- // during the boot window reads this server's initial `'main'`- // default and caches it in `current-branch-store` for the lifetime of- // the session. Mirrors the `handleDocumentList` gate; `.catch()` keeps- // the handler responsive on a degraded boot.- if (ready) {- await ready.catch((err: unknown) => {- log.warn(- { err, handler: 'server-info' },- '[api] ready gate rejected — responding with current state',- );+ const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);+ const assetPath = url.searchParams.get('path');+ const resolution = assetService.resolveServableAsset(assetPath);+ if (!resolution.ok) {+ const [status, type, title] = ASSET_SERVE_ERRORS[resolution.reason];+ errorResponse(res, status, type, title, {+ handler: 'asset',+ ...(resolution.cause !== undefined ? { cause: resolution.cause } : {}),});+ return;+ }+ const { asset } = resolution;+ const headers: Record<string, string> = {+ 'Content-Type': asset.contentType,+ 'Content-Length': String(asset.size),+ 'X-Content-Type-Options': 'nosniff',+ 'Content-Disposition': asset.disposition,+ 'Cache-Control': 'no-store',+ };+ if (asset.csp !== null) {+ headers['Content-Security-Policy'] = asset.csp;+ }+ const canonicalPath = asset.canonicalPath;+ res.writeHead(200, headers);+ try {+ await pipeline(createReadStream(canonicalPath), res);+ } catch (streamError) {+ // `writeHead(200)` ran above so `res.headersSent` is always true+ // here — the only correct cleanup is to destroy the socket so+ // the client sees a connection-level failure rather than a+ // truncated 200 with no error signal. Log structured before+ // destroying so a silent stream failure can still be triaged+ // from telemetry (the client-facing destruction is the only+ // wire signal it gets).+ log.error(+ {+ event: 'api.asset.pipeline-failed',+ handler: 'asset',+ assetPath,+ err: streamError,+ },+ '[asset] pipeline failed mid-stream',+ );+ if (!res.destroyed) {+ res.destroy(streamError instanceof Error ? streamError : undefined);+ }}- const currentBranch = durabilityState.getActiveBranch();- // `getDiskAckSVs` is wired by standalone boot; plugin mode (dev- // server) doesn't have a CC1Broadcaster and omits the field. The- // schema's `.optional()` keeps the response shape valid in both- // cases without a separate "no broadcaster" branch on the client.- const currentDiskAckSVs = getDiskAckSVs?.();- // Boot-phase timings (desktop startup instrumentation). Present only- // when the boot path called `startBootTimings` (standalone `bootServer`);- // the dev-server / plugin path leaves it `undefined`, so the schema's- // `.optional()` keeps the response valid. All bounded numbers — safe to- // disclose (per-process timing, no paths/content).- const boot = getBootTimings();- const collabClients = getCollabClientCount?.();- // `Cache-Control: no-store` matches the disclosure semantics: every- // field is per-process / per-moment state. A back/forward-cached- // 304 carrying a stale `currentDiskAckSVs` could silently corrupt- // the recycle baseline-selection on the next mismatch.- successResponse(- res,- 200,- ServerInfoSuccessSchema,- {- serverInstanceId,- currentBranch,- ...(currentDiskAckSVs !== undefined ? { currentDiskAckSVs } : {}),- ...(boot !== undefined ? { boot } : {}),- ...(collabClients !== undefined ? { collabClients } : {}),- },- {- handler: 'server-info',- extraHeaders: { 'Cache-Control': 'no-store' },- },- );} catch (e) {errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {- handler: 'server-info',+ handler: 'asset',cause: e,});}},- { handler: 'server-info', method: 'GET', skipBodyParse: true },- );-- const AcpCatalogAgentSchema = z.object({- id: z.string(),- name: z.string(),- version: z.string(),- description: z.string().optional(),- license: z.string().optional(),- iconUrl: z.string().optional(),- website: z.string().optional(),- source: z.enum(['registry', 'custom']),- /** A launchable distribution exists for this host platform. */- supported: z.boolean(),- featured: z.boolean(),- harness: z- .object({- cli: z.enum(['claude', 'codex', 'cursor', 'gemini', 'opencode', 'pi']),- availability: z.enum(['present', 'not-found', 'unknown']),- /** No `absent` member — see `HarnessCredentials`. */- credentials: z.enum(['present', 'unknown']),- })- .optional(),- });- const AcpCatalogSuccessSchema = z.object({- agents: z.array(AcpCatalogAgentSchema),- /** True when served from the offline fallback cache. */- stale: z.boolean(),- maxThreads: z.number(),- });-- const handleAcpCatalog = withValidation(- EmptyRequestSchema,- async (_req, res) => {- if (acpRegistry === undefined) {- errorResponse(res, 404, 'urn:ok:error:not-found', 'ACP catalog unavailable.', {- handler: 'acp-catalog',- });- return;- }- try {- const platform = registryPlatformKey();- const { agents, stale } = await acpRegistry.getCatalog();- const custom = (await loadAcpCustomAgents?.()) ?? [];- const harnessAvailability = await acpHarnessAvailability();- const rows = [- ...agents.map((a) => {- const harnessCli = ACP_AGENT_HARNESS_CLIS[a.id];- return {- id: a.id,- name: a.name,- version: a.version,- ...(a.description !== undefined ? { description: a.description } : {}),- ...(a.license !== undefined ? { license: a.license } : {}),- ...(a.icon !== undefined ? { iconUrl: a.icon } : {}),- ...(a.website !== undefined ? { website: a.website } : {}),- source: 'registry' as const,- supported:- a.distribution.npx !== undefined ||- a.distribution.uvx !== undefined ||- (platform !== null && a.distribution.binary?.[platform] !== undefined),- featured: FEATURED_AGENT_IDS.includes(a.id),- ...(harnessCli !== undefined- ? {- harness: {- cli: harnessCli,- availability: harnessAvailability[harnessCli]?.availability ?? 'unknown',- credentials: harnessAvailability[harnessCli]?.credentials ?? 'unknown',- },- }- : {}),- };- }),- ...custom.map((c: CustomAgentEntry) => ({- id: c.id,- name: c.name,- version: 'custom',- source: 'custom' as const,- supported: true,- featured: false,- })),- ];- successResponse(- res,- 200,- AcpCatalogSuccessSchema,- { agents: rows, stale, maxThreads: MAX_ACP_THREADS },- { handler: 'acp-catalog', extraHeaders: { 'Cache-Control': 'no-store' } },- );- } catch (e) {- errorResponse(- res,- 502,- 'urn:ok:error:registry-unreachable',- 'Agent registry unreachable.',- {- handler: 'acp-catalog',- cause: e,- },- );- }- },- { handler: 'acp-catalog', method: 'GET', skipBodyParse: true },- );-- async function handlePrincipal(req: IncomingMessage, res: ServerResponse): Promise<void> {- // Loopback + Host-header gate. The principal record discloses operator- // PII — `display_name` (real name) and `display_email` — sourced from- // local `git config`. Under `--host 0.0.0.0` (demos, shared dev boxes,- // Codespaces) this would otherwise be readable by any LAN peer or- // cross-origin page that bypasses the Origin allowlist (non-browser- // callers send no `Origin` header). Matches the same gate- // `handleMetricsAgentPresence` and `handleWorkspace` apply.- // Authorization runs BEFORE method dispatch so a bad Host never leaks- // "verb the endpoint expects" via the 405 response (OWASP ASVS V4.1.1).- if (!isRoutePeerAdmitted(req.socket.remoteAddress)) {- errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {- handler: 'principal',- });- return;- }- if (!isAllowedWorkspaceHostHeader(req.headers.host)) {- errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {- handler: 'principal',- });- return;- }- if (req.method !== 'GET') {- errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {- handler: 'principal',- extraHeaders: { Allow: 'GET' },- });- return;- }- const principal = getPrincipal?.() ?? null;- if (!principal) {- errorResponse(res, 404, 'urn:ok:error:principal-not-available', 'Principal not available.', {- handler: 'principal',- });- return;- }- successResponse(res, 200, PrincipalSuccessSchema, principal, { handler: 'principal' });- }-- async function handleEmbedDetect(req: IncomingMessage, res: ServerResponse): Promise<void> {- // Diagnostic endpoint for the Cursor / Codex / Claude Code embedded-viewer- // detection spikes. Reads from the in-process ring buffer populated in- // `onRequest` and surfaces boolean signals derived from the most recent- // entry's UA. Loopback + Host-header gated — same pattern as- // `handlePrincipal` / `handleMetricsAgentPresence`. Disclosed fields- // (full request headers, remote address) are local-editing-only signals.- if (!isRoutePeerAdmitted(req.socket.remoteAddress)) {- errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {- handler: 'embed-detect',- });- return;- }- if (!isAllowedWorkspaceHostHeader(req.headers.host)) {- errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {- handler: 'embed-detect',- });- return;- }- if (req.method !== 'GET') {- errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {- handler: 'embed-detect',- extraHeaders: { Allow: 'GET' },- });- return;- }- const entries = embedProbeRing.read();- successResponse(- res,- 200,- EmbedDetectSuccessSchema,- {- entries,- count: entries.length,- detection: deriveDetection(entries[0]),- },- { handler: 'embed-detect' },- );- }-- async function handleWorkspace(req: IncomingMessage, res: ServerResponse): Promise<void> {- // Authorization runs BEFORE method dispatch: reversing the order turns the- // method check into a fingerprinting oracle for unauth callers (GET → 403,- // POST → 405 discloses the verb the endpoint expects). See OWASP ASVS 4.0- // V4.1.1 — "perform access control on every request."- //- // Loopback-only: this endpoint discloses the absolute host filesystem path- // (including home directory / username). That's fine for the local-editing- // use case the rest of the API is designed for, but if the user configures- // `server.host: 0.0.0.0` (demos, shared dev boxes, Codespaces), we do NOT- // want to leak the host shape over the network or to cross-origin fetches.- // All loopback clients (including requests from a browser on the same- // machine) pass — connections from other interfaces are refused.- //- // DNS-rebinding defense: `req.socket.remoteAddress` will read `127.0.0.1`- // for any request that reached the socket via loopback, including requests- // triggered by a malicious page that rebinds its hostname to `127.0.0.1`.- // The Host-header allowlist below enforces that the caller actually spoke- // to us via `localhost` / `127.0.0.1` / `[::1]`, matching the mitigation- // in the Ethereum/geth JSON-RPC lineage. Same-origin fetches from the- // editor app pass; cross-origin rebinding attempts are refused.- if (!isRoutePeerAdmitted(req.socket.remoteAddress)) {- errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {- handler: 'workspace',- });- return;- }- if (!isAllowedWorkspaceHostHeader(req.headers.host)) {- errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {- handler: 'workspace',- });- return;- }- if (req.method !== 'GET') {- errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {- handler: 'workspace',- extraHeaders: { Allow: 'GET' },- });- return;- }- // Absolute, canonical contentDir so the client can build full filesystem- // paths (e.g. for the sidebar 'Copy path > Full path' action). Symlinks in- // the workspace root are resolved via realpath so the path matches on-disk- // truth. We treat error kinds in line with the persistence layer's symlink- // contract:- // - ENOENT: contentDir missing on disk → 200 with `symlinkResolved: false`- // and the unresolved path. Lets "Copy Path" still produce a meaningful- // value when the directory was deleted between server start and this- // request; the client decides whether to act on it.- // - ELOOP / EACCES / anything else: real filesystem error → 500. Matches- // persistence's stricter policy (cyclic symlinks are rejected- // everywhere) and avoids handing the user a path that won't resolve.- const resolvedRoot = resolve(contentDir);- let resolvedContentDir = resolvedRoot;- let symlinkResolved = true;- try {- resolvedContentDir = realpathSync(resolvedRoot);- } catch (err) {- const code = errnoCode(err);- if (code === 'ENOENT') {- log.warn(- { path: resolvedRoot },- '[workspace] contentDir does not exist; returning unresolved path',- );- symlinkResolved = false;- } else {- log.warn({ path: resolvedRoot, err }, '[workspace] realpath failed for contentDir');- errorResponse(- res,- 500,- 'urn:ok:error:internal-server-error',- 'Workspace realpath failed.',- { handler: 'workspace', detail: code ?? undefined, cause: err },- );- return;- }- }- // `pathSeparator` lets the client build full paths without guessing from- // the shape of `contentDir` (which breaks on Windows + forward-slash paths- // and on POSIX folders that contain a literal backslash in the name).- successResponse(- res,- 200,- WorkspaceSuccessSchema,- {- contentDir: resolvedContentDir,- pathSeparator: sep,- symlinkResolved,- },- { handler: 'workspace' },- );- }-- const assetService = createAssetService({- contentDir,- // `isPathIgnored` rather than `isExcluded` so the sibling-asset heuristic- // does not reject legitimate cross-directory references. Exclusion is- // reported as not-found: the wire shape stays identical to a missing file.- isPathIgnored: (relativePath) => contentFilter?.isPathIgnored(relativePath) ?? false,- getAttachmentFolderPath,- });- const ASSET_SERVE_ERRORS = {- 'missing-path': [400, 'urn:ok:error:invalid-request', 'Missing asset path.'],- 'unsupported-type': [415, 'urn:ok:error:unsupported-asset-type', 'Unsupported asset type.'],- 'not-found': [404, 'urn:ok:error:asset-not-found', 'Asset not found.'],- 'invalid-path': [400, 'urn:ok:error:invalid-request', 'Invalid asset path.'],- } as const;-- const handleAsset = withValidation(- EmptyRequestSchema,- async (req, res) => {- try {- const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);- const assetPath = url.searchParams.get('path');- const resolution = assetService.resolveServableAsset(assetPath);- if (!resolution.ok) {- const [status, type, title] = ASSET_SERVE_ERRORS[resolution.reason];- errorResponse(res, status, type, title, {- handler: 'asset',- ...(resolution.cause !== undefined ? { cause: resolution.cause } : {}),- });- return;- }- const { asset } = resolution;- const headers: Record<string, string> = {- 'Content-Type': asset.contentType,- 'Content-Length': String(asset.size),- 'X-Content-Type-Options': 'nosniff',- 'Content-Disposition': asset.disposition,- 'Cache-Control': 'no-store',- };- if (asset.csp !== null) {- headers['Content-Security-Policy'] = asset.csp;- }- const canonicalPath = asset.canonicalPath;- res.writeHead(200, headers);- try {- await pipeline(createReadStream(canonicalPath), res);- } catch (streamError) {- // `writeHead(200)` ran above so `res.headersSent` is always true- // here — the only correct cleanup is to destroy the socket so- // the client sees a connection-level failure rather than a- // truncated 200 with no error signal. Log structured before- // destroying so a silent stream failure can still be triaged- // from telemetry (the client-facing destruction is the only- // wire signal it gets).- log.error(- {- event: 'api.asset.pipeline-failed',- handler: 'asset',- assetPath,- err: streamError,- },- '[asset] pipeline failed mid-stream',- );- if (!res.destroyed) {- res.destroy(streamError instanceof Error ? streamError : undefined);- }- }- } catch (e) {- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {- handler: 'asset',- cause: e,- });- }- },- { handler: 'asset', method: 'GET', skipBodyParse: true },+ { handler: 'asset', method: 'GET', skipBodyParse: true },);/**@@ -8991,79 +8144,6 @@ export function createApiExtension({ handler: 'asset-text', method: 'GET', skipBodyParse: true },);- /** 24h in milliseconds — rescue buffers older than this are excluded/cleaned. */- const RESCUE_MAX_AGE_MS = 24 * 60 * 60 * 1000;-- const handleRescueList = withValidation(- EmptyRequestSchema,- async (_req, res) => {- try {- if (!shadowRef?.current) {- // No shadow repo configured = no rescue buffers; emit empty list (success).- successResponse(res, 200, RescueListSuccessSchema, [], { handler: 'rescue-list' });- return;- }-- const now = Date.now();- // `source: 'flat'` rows came from the shutdown-flush path (retained flat-- // file); `source: 'timeline'` rows came from reconcile-delete /- // branch-switch (migrated to saveInMemoryCheckpoint). Clients- // can treat both as interchangeable unless they need the checkpoint sha.- const entries: (RescueEntryFlat | (RescueEntryTimeline & TimelineRescueEntry))[] = [];-- const rescueDir = resolve(shadowRef.current.gitDir, 'rescue');- if (existsSync(rescueDir)) {- try {- const files = readdirSync(rescueDir).filter((f) => isSupportedDocFile(f));- for (const file of files) {- const filePath = resolve(rescueDir, file);- const stat = statSync(filePath);- const age = now - stat.mtimeMs;-- if (age > RESCUE_MAX_AGE_MS) {- try {- unlinkSync(filePath);- } catch (e) {- log.debug({ err: e }, '[rescue] cleanup failed (non-critical)');- }- continue;- }-- entries.push({- docName: stripDocExtension(file),- timestamp: stat.mtime.toISOString(),- size: stat.size,- source: 'flat',- });- }- } catch (err) {- log.error({ err }, '[rescue] Failed to list flat-file rescue buffers');- }- }-- // Timeline-ref source — merged in so the unified response surfaces all- // three rescue classes once the write migration ships.- try {- const branch = getCurrentBranch?.() ?? 'main';- const timelineEntries = await listRescueCheckpoints(shadowRef.current, branch);- for (const t of timelineEntries) {- entries.push({ ...t, source: 'timeline' });- }- } catch (err) {- log.error({ err }, '[rescue] Failed to list timeline-ref rescue checkpoints');- }-- successResponse(res, 200, RescueListSuccessSchema, entries, { handler: 'rescue-list' });- } catch (e) {- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {- handler: 'rescue-list',- cause: e,- });- }- },- { handler: 'rescue-list', method: 'GET', skipBodyParse: true },- );-const handleCreatePage = withValidation(CreatePageRequestSchema,async (_req, res, body) => {@@ -12707,40 +11787,6 @@ export function createApiExtension(},);- async function handleInstalledAgentsRoute(- req: IncomingMessage,- res: ServerResponse,- ): Promise<void> {- // Loopback + DNS-rebinding gate. Same contract the rest of the host-- // disclosure surface uses (`/api/workspace`, every `/api/local-op/*`) —- // this endpoint discloses a stable OS-level fingerprint of which AI- // agents are installed, readable without preflight under the permissive- // `Access-Control-Allow-Origin: *` that `/api/*` sets. Gating on- // `checkLocalOpSecurity` confines the fingerprint to same-machine,- // same-origin callers (the editor UI) and refuses cross-origin browser- // contexts + DNS-rebinding attempts that would otherwise succeed.- // `checkLocalOpSecurity` itself emits RFC 9457 problem+json on rejection.- if (!checkLocalOpSecurity(req, res, { handler: 'installed-agents' })) return;- try {- await handleInstalledAgents(req, res, installedAgentsCache.probeAll);- } catch (e) {- // Defensive: `handleInstalledAgents` catches internally, so this only- // fires on truly unexpected throws (e.g., probeAll synchronously- // throwing before its internal try/catch). Guard `headersSent` so we- // don't double-emit if the inner handler already wrote a response.- if (!res.headersSent) {- log.error(- { err: e, requestId: getRequestId(req) },- '[installed-agents] route wrapper failed',- );- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {- handler: 'installed-agents',- cause: e,- });- }- }- }-function validateFolderRel(raw: string,res: ServerResponse,@@ -13273,41 +12319,6 @@ export function createApiExtension(return false;}- /**- * Project-wide flat enumeration of every `<folder>/.ok/templates/*.md`.- * The single-template `/api/template` endpoint is per-folder + walks- * leaf → root for closest-wins resolution; this surface is the editor's- * empty-state list (every template the user can pick from, with the- * `source_folder` that owns each one). Skips the same dirs as the- * directory-scan walker — see `resolveProjectTemplates`.- */- const handleTemplatesList = withValidation(- EmptyRequestSchema,- catchErrors(- async (_req, res) => {- const resolvedContentDir = resolve(contentDir);- const result = await resolveProjectTemplates(resolvedContentDir);- // Drop `scope` from each entry — every flat-enumeration entry is- // implicitly `scope: 'local'` to its own `source_folder`, so the- // field carries no information here. `TemplatesListEntrySchema` is- // `.strict()` and would otherwise reject the response.- const templates = result.templates.map((t) => {- const { scope: _scope, ...rest } = t;- return rest;- });- successResponse(- res,- 200,- TemplatesListSuccessSchema,- { templates, truncated: result.truncated },- { handler: 'templates-list' },- );- },- { handler: 'templates-list', title: 'Failed to list templates.' },- ),- { handler: 'templates-list', method: 'GET', skipBodyParse: true },- );-// Generic frontmatter splitter for managed `.md` files (SKILL.md, etc.):// returns the parsed YAML frontmatter object + the body. Distinct from core's// `parseTemplateFile`, which parses the single-block TEMPLATE format@@ -20741,32 +19752,6 @@ export function createApiExtension({ handler: 'search' },);- const handleSkillInstallState = withValidation(- EmptyRequestSchema,- catchErrors(- async (_req, res) => {- const snapshot = await readSkillInstallStateSnapshot(homedir());- successResponse(- res,- 200,- SkillInstallStateSuccessSchema,- { ...snapshot },- {- handler: 'skill-install-state',- extraHeaders: { 'Cache-Control': 'no-store' },- },- );- },- { handler: 'skill-install-state', title: 'Failed to read skill install state.' },- ),- {- handler: 'skill-install-state',- method: 'GET',- skipBodyParse: true,- preBodyGate: (req, res) => checkLocalOpSecurity(req, res, { handler: 'skill-install-state' }),- },- );-async function handleHandoffDispatchRoute(req: IncomingMessage,res: ServerResponse,@@ -21634,105 +20619,6 @@ export function createApiExtension(},);- // `/api/config` — collab-bootstrap payload for the React shell. This server- // serves the SPA itself, so the shell fetches `/api/config` from the same- // origin (api-config.ts consumes it; the `--only ui` split-mode proxy in- // `packages/cli` emits the same shape): GET returns- // `{collabUrl, previewUrl, port}`. GET- // stays open like the other read-only bootstrap endpoints- // (document/pages/backlinks) — it carries no PII and only reflects the- // client's own Host back to itself. `lockDir` is the project's- // `.ok/local/` (the server-lock anchor); null when projectDir is unconfigured- // (some test harnesses), leaving collabUrl bootstrap intact.- const lockDir = projectDir ? getLocalDir(projectDir) : null;- async function handleApiConfig(req: IncomingMessage, res: ServerResponse): Promise<void> {- if (req.method === 'GET' || req.method === 'HEAD') {- try {- // Same-origin collab WS: the shell loaded from this server, so- // `ws(s)://<host>/collab` reaches the same process the request arrived- // on (scheme honors X-Forwarded-Proto — see collab-bootstrap-url.ts).- // Avoids the cross-port WS attempt sandboxed preview panes refuse. The- // Host value is the client's own header reflected back to itself (the- // Origin CORS gate in `onRequest` already refused cross-origin- // browsers); it is not independently vetted here. A genuinely absent- // Host yields a null collabUrl — a deliberate divergence from the- // split-mode UI proxy's- // `?? localhost:${resolvedPort}` fallback: this server has no single- // canonical advertised port to substitute, and the client falls back- // to a same-origin WS URL on a null. Node HTTP/1.1 always populates- // Host, so the null path is a malformed-request floor, not a normal case.- const collabUrl = collabUrlFromRequestHeaders(req.headers);- const port = lockDir ? (readServerLock(lockDir)?.port ?? 0) : 0;- // `singleFile` tells the React shell to drop project chrome for an- // ephemeral single-file session (`ok <file>`).- const payload = { collabUrl, previewUrl: null, port, singleFile: ephemeral };- // HEAD carries the same headers but no body; `successResponse` always- // writes a body, so the no-body verb stays a manual emit.- if (req.method === 'HEAD') {- res.setHeader('Content-Type', 'application/json');- res.setHeader('Cache-Control', 'no-store');- res.setHeader('X-Content-Type-Options', 'nosniff');- res.statusCode = 200;- res.end();- return;- }- successResponse(res, 200, ApiConfigSuccessSchema, payload, {- handler: 'api-config',- extraHeaders: { 'Cache-Control': 'no-store' },- });- } catch (e) {- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {- handler: 'api-config',- cause: e,- });- }- return;- }- errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {- handler: 'api-config',- extraHeaders: { Allow: 'GET, HEAD' },- });- }-- // `/api/config/diagnostics` — active config diagnostics across the user,- // committed-project, and project-local layers. Read-only and open like- // `/api/config`: the collector reads the files fresh per request (so a- // hand-edit or `ok config migrate` is reflected without a restart) and- // returns only structural findings — scope, file, key path, code, redirect —- // never a raw config value. `no-store` so a poll always sees current disk- // state.- async function handleConfigDiagnostics(req: IncomingMessage, res: ServerResponse): Promise<void> {- if (req.method === 'GET' || req.method === 'HEAD') {- try {- const payload = getConfigDiagnostics?.() ?? { diagnostics: [] };- // HEAD mirrors GET's headers with no body; `successResponse` always- // writes one, so the no-body verb stays a manual emit.- if (req.method === 'HEAD') {- res.setHeader('Content-Type', 'application/json');- res.setHeader('Cache-Control', 'no-store');- res.setHeader('X-Content-Type-Options', 'nosniff');- res.statusCode = 200;- res.end();- return;- }- successResponse(res, 200, ConfigDiagnosticsReportSchema, payload, {- handler: 'api-config-diagnostics',- extraHeaders: { 'Cache-Control': 'no-store' },- });- } catch (e) {- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {- handler: 'api-config-diagnostics',- cause: e,- });- }- return;- }- errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {- handler: 'api-config-diagnostics',- extraHeaders: { Allow: 'GET, HEAD' },- });- }-// ───────────────────── Embeddings API key — Account control ─────────────────// Loopback + Origin gated (checkLocalOpSecurity) set/clear for the// machine-global embeddings key. The key travels renderer → loopback POST body@@ -21946,92 +20832,11 @@ export function createApiExtension(},);- /**- * GET /api/semantic-status — read-only setup/coverage probe for the Settings- * UI. Reports the project-local `enabled` flag, `keyPresent` / `keySource`- * (an API key is resolvable — a free file/env read), `ready` (has the service- * warmed yet), `capable` (warmed AND a usable key found), and indexed coverage- * (embedded / total embeddable pages). Side-effect-free: NO embed, NO egress,- * NO warm (warming reads the key and — under the legacy keychain backend —- * could prompt). Returns an inert all-false/zero shape when the service is- * absent (dev/plugin mode).- */- const handleSemanticStatus = withValidation(- EmptyRequestSchema,- async (_req, res) => {- try {- // Report the service's CURRENT known state — do NOT call ensureWarm()- // (warming hydrates the cache; a read-only status GET shouldn't). `ready`- // stays false until the first real search warms it.- let enabled = false;- let ready = false;- let capable = false;- let embedded = 0;- if (semanticSearch) {- const status = semanticSearch.getStatus();- enabled = status.enabled;- ready = status.ready;- capable = status.capable;- embedded = status.embeddedCount;- }- // Resolve the SAME credential the embedder would, for this project +- // its configured endpoint, so status can't disagree with the real path.- // A free, prompt-free file/env read — no warm, no egress. The key itself- // is never returned; only `keyHint` (redacted last-4) so the UI can show- // WHICH key is set. `keyNotRequired` marks a loopback endpoint that needs- // no key at all, so the UI doesn't nag a keyless Ollama/LM Studio user.- const statusConfig = readSemanticProviderConfig?.();- const statusBaseUrl = statusConfig?.baseUrl ?? DEFAULT_EMBEDDINGS_BASE_URL;- const cred = await resolveEmbeddingsCredential(- new FileEmbeddingsBackend(embeddingsSecretsFile),- projectDir ?? contentDir,- statusBaseUrl,- );- const keyPresent = cred.apiKey !== null;- const keyNotRequired = !keyPresent && cred.keyless;- const keySource: 'project' | 'file' | 'env' | null = keyPresent- ? (cred.source as 'project' | 'file' | 'env')- : null;- // Last 4 chars only, and only when the key is long enough that those 4 are- // a negligible fraction (real provider keys are 40+ chars); never the key.- const keyHint = cred.apiKey && cred.apiKey.length >= 8 ? cred.apiKey.slice(-4) : null;- // Total embeddable pages = the same filtered set the search corpus uses.- let total = 0;- for (const [docName] of getFileIndex()) {- if (!isSystemDoc(docName) && !isConfigDoc(docName) && !isHiddenDocName(docName)) {- total += 1;- }- }- successResponse(- res,- 200,- SemanticIndexStatusSchema,- {- enabled,- keyPresent,- keyNotRequired,- keySource,- keyHint,- ready,- capable,- embedded,- total,- },- { handler: 'semantic-status', extraHeaders: { 'Cache-Control': 'no-store' } },- );- } catch (e) {- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {- handler: 'semantic-status',- cause: e,- });- }- },- { handler: 'semantic-status', method: 'GET', skipBodyParse: true },- );-- // ---- Markdown linter: effective config + per-doc lint + project audit ----- // The editor reads the effective config; the Settings GUI writes native- // `.markdownlint.*` rules through the markdownlint-config endpoint.+ // ---- Markdown linter: write-side rules + the lint-config epoch/generation+ // shared with the native lint-read group (http/lint-routes.ts) ----+ // The Settings GUI writes native `.markdownlint.*` rules through the+ // markdownlint-config endpoint; the read-side handlers (config, per-doc lint,+ // project audit) moved to the native lint group./*** Monotonic counter over server-side lint-config mutations, and the config@@ -22162,55 +20967,6 @@ export function createApiExtension(return unmatchedAppliesToProblems(slice.schemas, docFiles);}- const handleGetLintConfig = withValidation(- EmptyRequestSchema,- async (req, res) => {- try {- // A `?doc=` is accepted (the editor passes the active doc) but the- // effective config resolves per doc (cli2 cascade: nearest native- // file on the doc→root walk governs); no `?doc=` → root-level.- const url = new URL(req.url ?? '', 'http://localhost');- const docName = url.searchParams.get('doc');- if (docName !== null && (docName === '' || !isSafeDocName(docName))) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid doc.', {- handler: 'lint-config',- });- return;- }- const base = getLinterBaseConfig?.() ?? DEFAULT_LINTER_CONFIG;- const configProblems: string[] = [];- const native = resolveNativeConfigForDoc(contentDir, docName ?? undefined, (problem) =>- configProblems.push(problem),- );- const effective = composeFrontmatterSchemasConfig(- projectDir ?? contentDir,- composeEffectiveLinterConfig(base, native),- (problem) => configProblems.push(problem),- );- if (docName === null) configProblems.push(...unmatchedGlobProblems(effective));- successResponse(- res,- 200,- LintConfigResponseSchema,- { effective, configFile: native?.file ?? null, configProblems },- { handler: 'lint-config' },- );- } catch (e) {- errorResponse(- res,- 500,- 'urn:ok:error:internal-server-error',- 'Failed to resolve lint config.',- {- handler: 'lint-config',- cause: e,- },- );- }- },- { handler: 'lint-config', method: 'GET', skipBodyParse: true },- );-// Edit one rule in the project's native `.markdownlint.*` file (the source of// truth). Root-level only for now; returns the recomputed effective config// so the settings panel reflects the change.@@ -22372,312 +21128,6 @@ export function createApiExtension({ handler: 'frontmatter-schema', method: 'POST' },);- // Enumerate the project's `.ok/schemas/*.json` files (flat, top-level only)- // as project-root-relative paths for the mapping picker. A missing dir is- // an empty list, not an error; bounded so a pathological schemas dir can't- // produce an unbounded response.- const handleFrontmatterSchemasList = withValidation(- EmptyRequestSchema,- async (_req, res) => {- try {- const root = resolve(projectDir ?? contentDir);- // Two discovery sources: the flat tool-created `.ok/schemas/` scan,- // plus a filtered content walk for the ecosystem `*.schema.json`- // convention anywhere in the project. The walk deliberately does NOT- // re-admit `.ok`: the scan above already covers `.ok/schemas/`, and- // lifting ContentFilter's always-skip floor here would let this- // surface enumerate the rest of OK's internal state to find schemas.- const { schemas, truncated } = listProjectSchemaFiles(root);- const found = new Set(schemas);- let walkTruncated = false;- if (contentFilter !== undefined) {- const walk = streamShowAllEntries({- contentDir,- contentFilter,- dirFilter: null,- maxEntries: 20_000,- });- let walkResult = await walk.next();- while (!walkResult.done) {- const entry = walkResult.value;- const entryPath = entry.kind === 'asset' ? entry.path : undefined;- if (entryPath !== undefined && isFrontmatterSchemaAsset(entryPath)) {- const projectRel = relative(root, resolve(contentDir, entryPath));- if (!projectRel.startsWith('..') && !isAbsolute(projectRel)) found.add(projectRel);- }- walkResult = await walk.next();- }- walkTruncated = walkResult.value.truncated;- }- const merged = [...found].sort((a, b) => a.localeCompare(b));- successResponse(- res,- 200,- FrontmatterSchemasListSuccessSchema,- {- schemas: merged.slice(0, SCHEMA_LIST_CAP),- truncated: truncated || walkTruncated || merged.length > SCHEMA_LIST_CAP,- },- { handler: 'frontmatter-schemas-list' },- );- } catch (e) {- errorResponse(- res,- 500,- 'urn:ok:error:internal-server-error',- 'Failed to list frontmatter schemas.',- { handler: 'frontmatter-schemas-list', cause: e },- );- }- },- { handler: 'frontmatter-schemas-list', method: 'GET', skipBodyParse: true },- );-- /**- * Live CRDT source for a currently-loaded doc, else null. Lint reads must- * see the same bytes the editor and `/api/lint/fix` operate on: the disk- * file lags the CRDT behind the persistence debounce, and if a flush is- * ever lost the two diverge durably — a disk-only audit then reports- * problems the live doc no longer has and the Fix all sweep no-ops forever.- * Unloaded docs have no live copy; disk is authoritative for them.- */- const liveLintSourceFor = (docRelPath: string): string | null => {- const docName = docRelPath.replace(/\.(md|mdx)$/i, '');- const doc = hocuspocus.documents.get(docName);- return doc === undefined ? null : doc.getText('source').toString();- };-- const handleLintDoc = withValidation(- EmptyRequestSchema,- async (req, res) => {- try {- const url = new URL(req.url ?? '', 'http://localhost');- const docName = url.searchParams.get('doc') ?? '';- if (docName === '' || !isSafeDocName(docName)) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing or invalid doc.', {- handler: 'lint',- });- return;- }- const docRelPath = resolveDocFilePath(contentDir, docName);- if (docRelPath === null) {- errorResponse(res, 404, 'urn:ok:error:doc-not-found', 'Document not found.', {- handler: 'lint',- });- return;- }- const baseConfig = getLinterBaseConfig?.() ?? DEFAULT_LINTER_CONFIG;- const configWarnings: string[] = [];- const result = await lintDoc({- projectDir: projectDir ?? contentDir,- contentDir,- baseConfig,- docRelPath,- onConfigProblem: (problem) => configWarnings.push(problem),- liveSourceFor: liveLintSourceFor,- });- // Absent when there is nothing to report, matching the schema's- // documented contract and the three sibling lint emitters. `ran` is the- // field that is always present; do not carry that rule across to this one.- const lintWarnings = [...configWarnings, ...summarizeLintPluginFailures(result.failures)];- successResponse(- res,- 200,- LintDocResultSchema,- { ...result, ...(lintWarnings.length > 0 ? { warnings: lintWarnings } : {}) },- { handler: 'lint' },- );- } catch (e) {- if (e instanceof SymlinkEscapeError) {- errorResponse(res, 400, 'urn:ok:error:path-escape', 'Path escape detected.', {- handler: 'lint',- });- return;- }- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to lint document.', {- handler: 'lint',- cause: e,- });- }- },- { handler: 'lint', method: 'GET', skipBodyParse: true },- );-- // One cache per server instance (not module-scoped): its keys carry contentDir,- // but a per-server lifetime also means a restart starts cold, which is the- // right blast radius for a disk-stamp-keyed cache.- const auditCache = new AuditCache();- /**- * Audits in flight, keyed by scope + config fingerprint. Every window runs the- * freshness triggers independently, and the Problems panel can refresh at the- * same moment, so a single config change can ask for the same whole-project- * walk several times over. Coalescing makes them one walk instead of N cold- * ones that each finish too late to warm the others' cache.- *- * The walk yields to the event loop, so a request issued after a config- * mutation or a branch switch IS parsed while an earlier walk is still- * running and could attach to it. The fingerprint alone would not stop that:- * it covers the BASE config, which never carries markdownlint `rules` (those- * come from the native `.markdownlint.*` cascade) nor frontmatter-schema- * bodies, and says nothing at all about which branch's content is on disk.- * {@link readAuditGeneration} is what makes the key move, which is why it is- * read here per request rather than captured once. The per-file cache keys on- * the fully-resolved config and the file's disk stamp, so nothing is cached- * under the wrong rules or the wrong branch's bytes either way.- */- const auditFlight = createSingleFlight<ValidationAuditResult>();-- function runCoalescedAudit(- validators: readonly ProjectValidator[],- targetPath: string | undefined,- configFingerprint: string,- ): Promise<ValidationAuditResult> {- const key = `${configFingerprint} ${readAuditGeneration()} ${targetPath ?? ''}`;- return auditFlight.run(key, () => runValidationAudit(validators, { targetPath })).promise;- }-- /**- * A superseded walk has no plane to report, so the caller gets a retryable- * 409 rather than a stale or mixed one. The store-side effect is exactly the- * effect of any failed audit — previous entries stand — and whichever change- * superseded this walk has already broadcast its own CC1 channel- * (`lint-config` for a config mutation, `branch-switched` for a switch), so- * the corrective walk is scheduled without the caller doing anything.- */- function respondAuditSuperseded(res: ServerResponse, handler: string): void {- errorResponse(- res,- 409,- 'urn:ok:error:audit-superseded',- 'The lint configuration or branch changed while the audit was running; re-run it.',- { handler },- );- }-- const handleLintAudit = withValidation(- EmptyRequestSchema,- async (req, res) => {- try {- const url = new URL(req.url ?? '', 'http://localhost');- const rawTarget = url.searchParams.get('path');- const target = rawTarget === null || rawTarget === '' ? undefined : rawTarget;- // Absolute paths and traversal must not reach the walker: an audit- // response carries offending-text snippets, so an unchecked scope is- // an arbitrary-directory read for any connected agent.- if (target !== undefined && !isValidRelativeContentPath(target)) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid path.', {- handler: 'lint-audit',- });- return;- }- const baseConfig = getLinterBaseConfig?.() ?? DEFAULT_LINTER_CONFIG;- const result = await auditProject({- projectDir: projectDir ?? contentDir,- contentDir,- baseConfig,- targetPath: target,- liveSourceFor: liveLintSourceFor,- cache: auditCache,- auditGeneration: readAuditGeneration,- });- successResponse(res, 200, LintAuditResponseSchema, result, { handler: 'lint-audit' });- } catch (e) {- if (e instanceof AuditSupersededError) {- respondAuditSuperseded(res, 'lint-audit');- return;- }- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to audit project.', {- handler: 'lint-audit',- cause: e,- });- }- },- { handler: 'lint-audit', method: 'GET', skipBodyParse: true },- );-- // Unified validation audit: every registered project validator (markdownlint- // walk + derived-index dead-link read) merged into one source-tagged plane.- // Additive alongside /api/lint/audit and /api/dead-links, which keep their- // single-validator contracts.- const handleAudit = withValidation(- EmptyRequestSchema,- async (req, res) => {- try {- const url = new URL(req.url ?? '', 'http://localhost');- const rawTarget = url.searchParams.get('path');- let target = rawTarget === null || rawTarget === '' ? undefined : rawTarget;- // Absolute paths and traversal must not reach the validators: the- // lint walk reads file bytes under this scope, so an unchecked path- // is an arbitrary-directory read for any connected caller.- if (target !== undefined && !isValidRelativeContentPath(target)) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid path.', {- handler: 'audit',- });- return;- }- // `doc` scopes by docName (extension-less). The client freshness path- // knows docNames from disk-ack frames, never file extensions, so the- // extension resolution has to happen here. A doc indexed from a live- // CRDT session may not be on disk yet — fall back to the default- // extension so the links validator can still scope to it (mirrors the- // links validator's own fallback).- const rawDoc = url.searchParams.get('doc');- const docParam = rawDoc === null || rawDoc === '' ? undefined : rawDoc;- if (docParam !== undefined) {- if (target !== undefined || !isValidRelativeContentPath(docParam)) {- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid doc.', {- handler: 'audit',- });- return;- }- target = resolveDocFilePath(contentDir, docParam) ?? `${docParam}.md`;- }- const baseConfig = getLinterBaseConfig?.() ?? DEFAULT_LINTER_CONFIG;- const validators = createProjectValidators({- projectDir: projectDir ?? contentDir,- contentDir,- baseConfig,- liveSourceFor: liveLintSourceFor,- derivedDocumentIndex: derivedDocumentIndex ?? null,- linksValidation: getLinksValidationSetting?.(),- admittedDocNames: collectAdmittedDocNames,- docFilePathFor: (docName) => resolveDocFilePath(contentDir, docName),- cache: auditCache,- auditGeneration: readAuditGeneration,- });- const result = await runCoalescedAudit(- validators,- target,- AuditCache.fingerprintConfig(baseConfig),- );- // `counts=1` tallies the same plane instead of enumerating it — the- // freshness path behind file-tree tints wants per-file counts, and on a- // large KB the enumerated bodies are tens of MB it discards on arrival.- if (url.searchParams.get('counts') === '1') {- successResponse(- res,- 200,- ValidationAuditCountsResponseSchema,- toValidationCountsPlane(result),- { handler: 'audit' },- );- return;- }- successResponse(res, 200, ValidationAuditResponseSchema, result, { handler: 'audit' });- } catch (e) {- if (e instanceof AuditSupersededError) {- respondAuditSuperseded(res, 'audit');- return;- }- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to audit project.', {- handler: 'audit',- cause: e,- });- }- },- { handler: 'audit', method: 'GET', skipBodyParse: true },- );-const handleLintFix = withValidation(LintFixRequestSchema,async (_req, res, body) => {@@ -23134,26 +21584,21 @@ export function createApiExtension();const routes: Record<string, (req: IncomingMessage, res: ServerResponse) => Promise<void>> = {- '/api/config': handleApiConfig,- '/api/config/diagnostics': handleConfigDiagnostics,'/api/generated-index/settings': handleGeneratedIndexSettings,'/api/comments': handleCommentsRoute,'/api/comment': handleCommentRoute,'/api/asset': handleAsset,'/api/asset-text': handleAssetText,- '/api/comment-counts': handleCommentCounts,'/api/link-preview': handleLinkPreview,'/api/folder-config': handleFolderConfig,'/api/saved-themes': handleSavedThemesList,'/api/saved-theme': handleSavedTheme,'/api/template': handleTemplate,'/api/template/import': handleTemplateImport,- '/api/templates': handleTemplatesList,'/api/skill': handleSkill,'/api/skill-file': handleSkillFile,'/api/skill-file/rename': handleSkillFileRename,'/api/skills': handleSkillsList,- '/api/skills/installed': handleSkillsInstalled,'/api/skills/search': handleSkillsSearch,'/api/skills/popular': handleSkillsPopular,'/api/skills/publisher': handleSkillsPublisher,@@ -23176,15 +21621,9 @@ export function createApiExtension('/api/skill/track-in-git': handleSkillTrackInGit,'/api/skill-targets': handleSkillTargets,'/api/search': handleSearch,- '/api/semantic-status': handleSemanticStatus,- '/api/lint/config': handleGetLintConfig,'/api/lint/markdownlint-config': handleWriteMarkdownlintRule,'/api/lint/frontmatter-schema': handleWriteFrontmatterSchema,- '/api/lint/frontmatter-schemas': handleFrontmatterSchemasList,- '/api/lint': handleLintDoc,- '/api/lint/audit': handleLintAudit,'/api/lint/fix': handleLintFix,- '/api/audit': handleAudit,'/api/create-page': handleCreatePage,'/api/create-folder': handleCreateFolder,'/api/duplicate-path': handleDuplicatePath,@@ -23201,11 +21640,7 @@ export function createApiExtension('/api/agent-activity': handleAgentActivity,'/api/agent-burst-diff': handleAgentBurstDiff,'/api/save-version': handleSaveVersion,- '/api/history': handleHistory,'/api/rollback': handleRollback,- '/api/__embed-detect': handleEmbedDetect,- '/api/server-info': handleServerInfo,- '/api/acp/catalog': handleAcpCatalog,'/api/share/construct-url': handleShareConstructUrl,'/api/share/target-status': handleShareTargetStatus,'/api/git/branch-info': handleBranchInfo,@@ -23214,9 +21649,6 @@ export function createApiExtension('/api/share/publish/owners': handleSharePublishOwners,'/api/share/publish/name-check': handleSharePublishNameCheck,'/api/share/publish': handleSharePublish,- '/api/principal': handlePrincipal,- '/api/rescue': handleRescueList,- '/api/workspace': handleWorkspace,'/api/sync/status': handleSyncStatus,'/api/sync/trigger': handleSyncTrigger,'/api/sync/conflicts': handleSyncConflicts,@@ -23236,11 +21668,9 @@ export function createApiExtension('/api/local-op/embeddings/set-key': handleLocalOpEmbeddingsSetKey,'/api/local-op/embeddings/clear-key': handleLocalOpEmbeddingsClearKey,'/api/local-op/embeddings/test': handleLocalOpEmbeddingsTest,- '/api/installed-agents': handleInstalledAgentsRoute,'/api/spawn-cursor': handleSpawnCursorRoute,'/api/handoff': handleHandoffDispatchRoute,'/api/install-skill': handleInstallSkill,- '/api/skill/install-state': handleSkillInstallState,'/api/seed/plan': handleSeedPlan,'/api/seed/apply': handleSeedApply,'/api/seed/install-pack-skill': handleSeedInstallPackSkill,@@ -23341,19 +21771,6 @@ export function createApiExtension(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',- // 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) =>@@ -23389,7 +21806,78 @@ export function createApiExtension(isAllowedWorkspaceHostHeader,log,});- const nativeGroups = [linkGraphRoutes, metricsRoutes, documentRoutes];+ const configSystemRoutes = createConfigSystemRoutes({+ contentDir,+ projectDir,+ ephemeral,+ log,+ ready,+ durabilityState,+ serverInstanceId,+ getDiskAckSVs,+ getCollabClientCount,+ getConfigDiagnostics,+ acpRegistry,+ loadAcpCustomAgents,+ acpHarnessAvailability,+ isRoutePeerAdmitted,+ isAllowedWorkspaceHostHeader,+ checkLocalOpSecurity,+ getPrincipal,+ semanticSearch,+ readSemanticProviderConfig,+ embeddingsSecretsFile,+ getFileIndex,+ shadowRef,+ getCurrentBranch,+ installedAgentsCache,+ });+ const lintRoutes = createLintRoutes({+ hocuspocus,+ contentDir,+ projectDir,+ contentFilter,+ isSafeDocName,+ resolveDocFilePath,+ isValidRelativeContentPath,+ streamShowAllEntries,+ getLinterBaseConfig,+ getLinksValidationSetting,+ derivedDocumentIndex,+ collectAdmittedDocNames,+ unmatchedGlobProblems,+ readAuditGeneration,+ });+ const historyRoutes = createHistoryRoutes({+ contentRoot,+ log,+ shadowRef,+ flushGitCommit,+ commitOkArtifactWrite,+ getCurrentBranch,+ validateFolderRel,+ safeDocPath,+ docTreePathCandidates,+ });+ const skillsReadRoutes = createSkillsReadRoutes({+ contentDir,+ projectDir,+ homeDirOverride,+ skillsHome,+ isSafeDocName,+ commentService,+ enumerateInstalledSkillsCached,+ checkLocalOpSecurity,+ });+ const nativeGroups = [+ linkGraphRoutes,+ metricsRoutes,+ documentRoutes,+ configSystemRoutes,+ lintRoutes,+ historyRoutes,+ skillsReadRoutes,+ ];// "A route lives in exactly one router" — enforced at construction, not// just documented; covers every group aggregated into the native paths.// Throw semantics pinned in `http/http-app.test.ts`.diff --git a/packages/server/src/api-history-composition.test.ts b/packages/server/src/api-history-composition.test.tsnew file mode 100644index 000000000..af91beaa6--- /dev/null+++ b/packages/server/src/api-history-composition.test.ts@@ -0,0 +1,85 @@+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 } from './composition-rig.test-helper.ts';++/**+ * Characterization: the natively-routed version-history read group over the+ * composed `bootServer` stack. This is the SECOND native group to carry a+ * DYNAMIC legacy prefix — `link-graph-routes.ts`'s `/api/tags/:name` was the+ * first; both use a Hono `/api/*` wildcard whose table `resolve` re-expresses+ * the legacy fall-through. The two diverge on malformed input by design:+ * `tags` returns a typed 400, while `history/:sha` keeps the legacy generic+ * 500 (sha decode inside `dispatch`) to hold byte parity with the lifted+ * handler.+ *+ * The shared `/api/*` admission gates are owned by+ * `api-admission-composition.test.ts`; this suite pins only what discriminates+ * the group: native registration of both the exact route and the dynamic+ * prefix, and the read/edge-case statuses.+ */++const A_SHA = 'a'.repeat(40);++let tmpRoot: string;+let server: BootedServer;++beforeAll(async () => {+ tmpRoot = await mkdtemp(resolve(tmpdir(), 'ok-history-native-'));+ const contentDir = mkdtempSync(resolve(tmpRoot, 'content-'));+ writeFileSync(resolve(contentDir, 'alpha.md'), '# Alpha\n\nBody.\n', 'utf-8');+ server = await bootCompositionRig(contentDir);+ await server.ready;+}, 60_000);++afterAll(async () => {+ await server?.destroy();+ await rm(tmpRoot, { recursive: true, force: true });+});++describe('history group over the composed listener — served natively', () => {+ test('both the exact route and the dynamic prefix answer a wrong method with 405 + Allow: GET', async () => {+ // Registration proof: an unregistered path returns the pipeline's generic+ // `/api/*` 404; a registered route (exact or dynamic) 405s the wrong verb.+ for (const path of ['/api/history', `/api/history/${A_SHA}`]) {+ const res = await fetch(`http://127.0.0.1:${server.port}${path}`, { method: 'POST' });+ expect(res.status, path).toBe(405);+ expect(res.headers.get('allow'), path).toBe('GET');+ }+ });++ test('the exact route serves a 200 timeline natively', async () => {+ const res = await fetch(`http://127.0.0.1:${server.port}/api/history?docName=alpha`);+ expect(res.status).toBe(200);+ expect(res.headers.get('content-type')).toBe('application/json');+ expect(res.headers.get('x-request-id')).not.toBeNull();+ });++ test('the dynamic /api/history/:sha prefix reaches handleHistoryVersion natively', async () => {+ // A 40-hex sha resolves through the `/api/history/*` wildcard to+ // handleHistoryVersion, which emits its OWN `doc-not-found` 404 for an+ // absent commit — distinct from the pipeline route-miss `not-found`, so+ // this proves the dynamic leg dispatches out of the legacy resolve+ // fall-through and into the native handler.+ const res = await fetch(`http://127.0.0.1:${server.port}/api/history/${A_SHA}?docName=alpha`);+ expect(res.status).toBe(404);+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:doc-not-found');+ });++ test('an empty sha (`/api/history/`) resolves to the :sha template with no dispatch (404)', async () => {+ // Preserves the legacy edge case: empty tail → no dispatch → the pipeline's+ // explicit 404 under the `/api/history/:sha` template.+ const res = await fetch(`http://127.0.0.1:${server.port}/api/history/`);+ expect(res.status).toBe(404);+ });++ test('both chained groups answer on one server (multi-group dispatch)', async () => {+ const linkGraph = await fetch(`http://127.0.0.1:${server.port}/api/backlinks?docName=alpha`);+ expect(linkGraph.status).toBe(200);+ const history = await fetch(`http://127.0.0.1:${server.port}/api/history?docName=alpha`);+ expect(history.status).toBe(200);+ });+});diff --git a/packages/server/src/api-lint-composition.test.ts b/packages/server/src/api-lint-composition.test.tsnew file mode 100644index 000000000..b6729cf6b--- /dev/null+++ b/packages/server/src/api-lint-composition.test.ts@@ -0,0 +1,78 @@+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 } from './composition-rig.test-helper.ts';++/**+ * Characterization: the natively-routed lint + audit read group over the+ * composed `bootServer` stack — the earlier groups' tables decline these URLs+ * and the chain falls through here. These are all ungated reads (no inline+ * loopback/Host gate); the shared `/api/*` admission gates are owned by+ * `api-admission-composition.test.ts`, so this suite pins only what+ * discriminates the group: native registration and the read bodies.+ */++/** GET requests that serve a 200 read in the composition rig. */+const READ_GETS = [+ '/api/lint/config',+ '/api/lint/frontmatter-schemas',+ '/api/lint?doc=alpha',+ '/api/lint/audit',+ '/api/audit',+];++/** The base paths — method-gated, so a POST answers 405 when registered. */+const ALL_ROUTES = [+ '/api/lint/config',+ '/api/lint/frontmatter-schemas',+ '/api/lint',+ '/api/lint/audit',+ '/api/audit',+];++let tmpRoot: string;+let server: BootedServer;++beforeAll(async () => {+ tmpRoot = await mkdtemp(resolve(tmpdir(), 'ok-lint-native-'));+ const contentDir = mkdtempSync(resolve(tmpRoot, 'content-'));+ writeFileSync(resolve(contentDir, 'alpha.md'), '# Alpha\n\nBody.\n', 'utf-8');+ server = await bootCompositionRig(contentDir);+ await server.ready;+}, 60_000);++afterAll(async () => {+ await server?.destroy();+ await rm(tmpRoot, { recursive: true, force: true });+});++describe('lint group over the composed listener — served natively', () => {+ test('every route in the group is registered natively (POST → 405 + Allow: GET)', async () => {+ for (const path of ALL_ROUTES) {+ const res = await fetch(`http://127.0.0.1:${server.port}${path}`, { method: 'POST' });+ expect(res.status, path).toBe(405);+ expect(res.headers.get('allow'), path).toContain('GET');+ }+ });++ test('every read serves a 200 body natively (application/json + x-request-id)', async () => {+ for (const path of READ_GETS) {+ const res = await fetch(`http://127.0.0.1:${server.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('both chained groups answer on one server (multi-group dispatch)', async () => {+ // The link/graph group resolves first in the chain; this group only+ // answers after the earlier groups decline. One server, both arms live.+ const linkGraph = await fetch(`http://127.0.0.1:${server.port}/api/backlinks?docName=alpha`);+ expect(linkGraph.status).toBe(200);+ const lintConfig = await fetch(`http://127.0.0.1:${server.port}/api/lint/config`);+ expect(lintConfig.status).toBe(200);+ });+});diff --git a/packages/server/src/api-request-id.test.ts b/packages/server/src/api-request-id.test.tsindex 805904382..cb55c108e 100644--- a/packages/server/src/api-request-id.test.ts+++ b/packages/server/src/api-request-id.test.ts@@ -11,7 +11,11 @@ import { tmpdir } from 'node:os';import { join } from 'node:path';import { Readable } from 'node:stream';import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';-import { createApiExtension } from './api-extension.ts';+// Import the test-helper wrapper (not the base factory): its `onRequest`+// dispatches the native route groups ahead of the legacy hook, so ported paths+// like the dynamic `/api/history/:sha` reach their real handler + access-log+// template instead of the legacy `/api/*` 404 fallback.+import { createApiExtension } from './api-extension.test-helper.ts';import type { FileIndexEntry } from './file-watcher.ts';import { loggerFactory } from './logger.ts';diff --git a/packages/server/src/api-search-semantic-factory.test.ts b/packages/server/src/api-search-semantic-factory.test.tsindex 46ae12b77..56130396f 100644--- a/packages/server/src/api-search-semantic-factory.test.ts+++ b/packages/server/src/api-search-semantic-factory.test.ts@@ -109,6 +109,19 @@ async function callViaServer(url: string,bodyObj?: Record<string, unknown>,): Promise<unknown> {+ // Natively-routed groups take precedence in the composed server — their Hono+ // routes match ahead of the legacy `onRequest` catch-all — so mirror that+ // order here: try the native dispatch first, then fall back to the legacy+ // `onRequest` chain. Several `/api/*` reads (e.g. `semantic-status`) now serve+ // from a native group, where the legacy pipeline would answer 404.+ {+ const req = makeReq(method, url, bodyObj === undefined ? '' : JSON.stringify(bodyObj));+ const { res, captured } = makeRes();+ if (await srv.nativeApi.dispatch(req, res)) {+ expect(captured.status).toBe(200);+ return JSON.parse(captured.body);+ }+ }const onRequestExts = srv.hocuspocus.configuration.extensions.filter((e,diff --git a/packages/server/src/api-skills-read-composition.test.ts b/packages/server/src/api-skills-read-composition.test.tsnew file mode 100644index 000000000..0982c56b4--- /dev/null+++ b/packages/server/src/api-skills-read-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,+ makeCaptureRes,+ makeSyntheticReq,+} from './composition-rig.test-helper.ts';+import { createSkillsReadRoutes, type SkillsReadRouteDeps } from './http/skills-read-routes.ts';+import { checkLocalOpSecurity } from './local-op-security.ts';++/**+ * Characterization: the natively-routed skills + templates read group. Same+ * two-layer proof as `api-config-system-composition.test.ts` — the booted rig+ * pins native registration + read bodies (the shared `/api/*` admission gates+ * are owned by `api-admission-composition.test.ts`), and a handler-level block+ * pins `skill/install-state`'s `checkLocalOpSecurity` pre-body gate, which the+ * pipeline would otherwise answer before the handler runs.+ *+ * `/api/skills` (the skills-list read) deliberately stays in the extension —+ * its shared mutable catalog cache moves with the skills mutation family — so+ * it is NOT part of this group.+ */++function buildSkillsReadRoutes(overrides: Partial<SkillsReadRouteDeps> = {}) {+ return createSkillsReadRoutes({+ contentDir: '/tmp/ok-skills-read-unit',+ projectDir: undefined,+ homeDirOverride: '/tmp/ok-skills-read-unit-home',+ skillsHome: '/tmp/ok-skills-read-unit-home',+ isSafeDocName: () => true,+ commentService: { countThreads: async () => new Map<string, number>() },+ enumerateInstalledSkillsCached: (() => ({+ skills: [],+ packs: [],+ })) as unknown as SkillsReadRouteDeps['enumerateInstalledSkillsCached'],+ checkLocalOpSecurity,+ ...overrides,+ });+}++async function dispatch(+ group: ReturnType<typeof createSkillsReadRoutes>,+ path: string,+ reqOpts: Parameters<typeof makeSyntheticReq>[0],+): Promise<{ status: number; body: { type?: string; title?: string } }> {+ const resolved = group.table.resolve(path);+ if (!resolved?.dispatch) throw new Error(`no dispatch for ${path}`);+ const req = makeSyntheticReq({ url: path, ...reqOpts });+ const { res, captured } = makeCaptureRes();+ await resolved.dispatch(req, res);+ return {+ status: captured.status,+ body: captured.body ? (JSON.parse(captured.body) as { type?: string; title?: string }) : {},+ };+}++/**+ * GET routes that serve a 200 read over the booted rig. `skill/install-state`+ * is intentionally absent: it reads the real `homedir()` directly (a seam+ * bypass flagged as a follow-up), so its coverage here is the handler-level+ * gate pin + the POST→405 registration pin, not a $HOME-dependent 200.+ */+const READ_200 = ['/api/comment-counts?docNames=alpha', '/api/skills/installed', '/api/templates'];++/** Every route in the group — method-gated, so a POST answers 405 when registered. */+const ALL_ROUTES = [+ '/api/comment-counts',+ '/api/skills/installed',+ '/api/templates',+ '/api/skill/install-state',+];++let tmpRoot: string;+let server: BootedServer;++beforeAll(async () => {+ tmpRoot = await mkdtemp(resolve(tmpdir(), 'ok-skills-read-native-'));+ const contentDir = mkdtempSync(resolve(tmpRoot, 'content-'));+ writeFileSync(resolve(contentDir, 'alpha.md'), '# Alpha\n\nBody.\n', 'utf-8');+ server = await bootCompositionRig(contentDir);+ await server.ready;+}, 60_000);++afterAll(async () => {+ await server?.destroy();+ await rm(tmpRoot, { recursive: true, force: true });+});++describe('skills-read group over the composed listener — served natively', () => {+ test('every route in the group is registered natively (POST → 405 + Allow: GET)', async () => {+ for (const path of ALL_ROUTES) {+ const res = await fetch(`http://127.0.0.1:${server.port}${path}`, { method: 'POST' });+ expect(res.status, path).toBe(405);+ expect(res.headers.get('allow'), path).toContain('GET');+ }+ });++ test('every read serves a 200 body natively (application/json + x-request-id)', async () => {+ for (const path of READ_200) {+ const res = await fetch(`http://127.0.0.1:${server.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('both chained groups answer on one server (multi-group dispatch)', async () => {+ const linkGraph = await fetch(`http://127.0.0.1:${server.port}/api/backlinks?docName=alpha`);+ expect(linkGraph.status).toBe(200);+ const templates = await fetch(`http://127.0.0.1:${server.port}/api/templates`);+ expect(templates.status).toBe(200);+ });+});++describe('skills-read inline gate — observable only at the handler layer', () => {+ test('skill/install-state short-circuits on checkLocalOpSecurity (foreign Origin → its own invalid-origin)', async () => {+ // Driven through the REAL `checkLocalOpSecurity` (not a stub): a loopback+ // peer with a foreign Origin passes the peer check and fails the origin+ // check, so the pre-body gate emits its OWN title — distinct from the+ // pipeline's `'Origin not allowed.'`. Only observable here, since the+ // pipeline's origin gate would answer first over HTTP.+ const out = await dispatch(buildSkillsReadRoutes(), '/api/skill/install-state', {+ remoteAddress: '127.0.0.1',+ origin: 'https://evil.example.com',+ });+ expect(out.status).toBe(403);+ expect(out.body.type).toBe('urn:ok:error:invalid-origin');+ expect(out.body.title).toBe('Origin header is not a permitted loopback origin.');+ });+});diff --git a/packages/server/src/boot.ts b/packages/server/src/boot.tsindex 8ab2ff36e..1d4737fab 100644--- a/packages/server/src/boot.ts+++ b/packages/server/src/boot.ts@@ -220,6 +220,7 @@ export interface BootServerOptions| 'embeddingsKeyStore'| 'singleDocRelPath'| 'ephemeral'+ | 'configHomedirOverride'> {/*** The project's loaded `Config` (parsed from `.ok/config.yml`,@@ -823,6 +824,7 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {embeddingsKeyStore: opts.embeddingsKeyStore,singleDocRelPath: opts.singleDocRelPath,ephemeral: opts.ephemeral,+ configHomedirOverride: opts.configHomedirOverride,});const {diff --git a/packages/server/src/composition-rig.test-helper.ts b/packages/server/src/composition-rig.test-helper.tsindex 4335fa991..e2cd5f397 100644--- a/packages/server/src/composition-rig.test-helper.ts+++ b/packages/server/src/composition-rig.test-helper.ts@@ -1,6 +1,9 @@-import { mkdirSync, writeFileSync } from 'node:fs';+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';+import type { IncomingMessage, ServerResponse } from 'node:http';import { request as httpRequest } from 'node:http';+import { tmpdir } from 'node:os';import { resolve } from 'node:path';+import { Readable } from 'node:stream';import { OK_DIR } from '@inkeep/open-knowledge-core';import { type BootedServer, type BootServerOptions, bootServer } from './boot.ts';import { ConfigSchema } from './config/schema.ts';@@ -31,7 +34,15 @@ export async function bootCompositionRig(overrides: Partial<BootServerOptions> = {},): Promise<BootedServer> {seedOkScaffold(contentDir);- return bootServer({+ // Isolate the home-dir scan on a dedicated empty tmpdir (NOT `contentDir`,+ // which would collapse the home + project config tiers onto one `.ok/`):+ // without an override, `homeDirOverride`/`skillsHome` fall through to the+ // runner's real `$HOME`, so `/api/skills/installed` enumerates the+ // developer's `~/.claude`. Computed BEFORE the boot so the mkdtemp is skipped+ // when a scope-separation suite supplies its own home.+ const ownedHome =+ overrides.configHomedirOverride ?? mkdtempSync(resolve(tmpdir(), 'ok-rig-home-'));+ const booted = await bootServer({host: '127.0.0.1',config: TEST_CONFIG,contentDir,@@ -40,7 +51,97 @@ export async function bootCompositionRig(gitEnabled: false,idleShutdownMs: null,...overrides,+ configHomedirOverride: ownedHome,});+ // The rig owns what it created — reap it on the teardown every consumer+ // already calls, rather than pushing cleanup onto each call site. A+ // caller-supplied home is left to its owner. (`destroy` is a plain mutable+ // property on a non-frozen object, so wrapping it is safe.)+ if (overrides.configHomedirOverride === undefined) {+ const inner = booted.destroy;+ booted.destroy = async (reason) => {+ // try/finally so the home is reaped even if the inner destroy throws its+ // AggregateError (a teardown-step timeout under CI load is documented,+ // not hypothetical) — mirrors bootServer's own destroy wrap.+ try {+ await inner(reason);+ } finally {+ rmSync(ownedHome, { recursive: true, force: true });+ }+ };+ }+ return booted;+}++/**+ * A synthetic `IncomingMessage` for HANDLER-LEVEL pins that dispatch a route's+ * handler directly (via `group.table.resolve(path)?.dispatch`), bypassing the+ * shared `/api/*` pipeline. That bypass is the point: `createApiRequestPipeline`+ * runs the origin gate and the universal `/api/*` peer + Host read gate before+ * it dispatches any route, so a handler's INLINE loopback/Host/local-op gate is+ * only observable when the handler runs without the pipeline in front of it.+ */+export function makeSyntheticReq(opts: {+ method?: string;+ url?: string;+ host?: string;+ origin?: string;+ remoteAddress?: string;+}): IncomingMessage {+ const req = Readable.from(Buffer.from('')) as unknown as IncomingMessage;+ req.method = opts.method ?? 'GET';+ req.url = opts.url ?? '/';+ req.headers = {+ host: opts.host ?? '127.0.0.1',+ ...(opts.origin !== undefined ? { origin: opts.origin } : {}),+ };+ req.socket = {+ remoteAddress: opts.remoteAddress ?? '127.0.0.1',+ } as unknown as IncomingMessage['socket'];+ return req;+}++export interface CapturedRes {+ status: number;+ headers: Record<string, string | number | string[] | undefined>;+ body: string;+}++/**+ * A minimal `ServerResponse` that records what the wire emitters+ * (`errorResponse` / `successResponse`) write — status, headers, body — and+ * carries the `headersSent` / `writableEnded` / `destroyed` flags their+ * triple-guard reads.+ */+export function makeCaptureRes(): { res: ServerResponse; captured: CapturedRes } {+ const captured: CapturedRes = { status: 0, headers: {}, body: '' };+ const res = {+ headersSent: false,+ writableEnded: false,+ destroyed: false,+ statusCode: 0,+ writeHead(status: number, headers?: Record<string, string | number | string[]>) {+ captured.status = status;+ if (headers)+ for (const [k, v] of Object.entries(headers)) captured.headers[k.toLowerCase()] = v;+ (res as { headersSent: boolean }).headersSent = true;+ return res;+ },+ setHeader(key: string, value: string | number | string[]) {+ captured.headers[key.toLowerCase()] = value;+ },+ getHeader(key: string) {+ return captured.headers[key.toLowerCase()];+ },+ end(body?: string) {+ // Handlers that set `res.statusCode` directly (the HEAD branches) instead+ // of calling writeHead surface their status here.+ if (captured.status === 0) captured.status = (res as { statusCode: number }).statusCode;+ if (body !== undefined) captured.body = body;+ (res as { writableEnded: boolean }).writableEnded = true;+ },+ } as unknown as ServerResponse;+ return { res, captured };}export interface RawResponse {diff --git a/packages/server/src/http/config-system-routes.ts b/packages/server/src/http/config-system-routes.tsnew file mode 100644index 000000000..55ff6cce7--- /dev/null+++ b/packages/server/src/http/config-system-routes.ts@@ -0,0 +1,857 @@+/**+ * The config + server-info read family — `config`, `config/diagnostics`,+ * `server-info`, `principal`, `workspace`, `semantic-status`, `acp/catalog`,+ * `installed-agents`, `__embed-detect`, `rescue` — the fourth natively-routed+ * Wave 2 group. Same lift shape as `link-graph-routes.ts` /+ * `metrics-routes.ts` / `document-routes.ts`: what the handlers closed over in+ * the extension arrives as {@link ConfigSystemRouteDeps}, the handler bodies+ * are unchanged, and the extension composes this group's table into its+ * `nativeApi` handle while the legacy dispatch record loses the paths in the+ * same change.+ *+ * `principal`, `workspace`, `installed-agents`, and `__embed-detect` carry+ * their loopback + Host / local-op gates INLINE, ahead of method dispatch (a+ * bad Host / peer must never learn the verb via 405). That contract is+ * different from the pipeline's `isMutating` mechanism, so these gates stay in+ * the handler bodies and `isMutating` stays false. The peer + Host predicates+ * arrive as deps because the extension widens them when the server is exposed.+ */++import { existsSync, readdirSync, realpathSync, statSync, unlinkSync } from 'node:fs';+import type { IncomingMessage, ServerResponse } from 'node:http';+import { resolve, sep } from 'node:path';+import {+ ApiConfigSuccessSchema,+ type ConfigDiagnosticsReport,+ ConfigDiagnosticsReportSchema,+ DEFAULT_EMBEDDINGS_BASE_URL,+ EmbedDetectSuccessSchema,+ EmptyRequestSchema,+ isHiddenDocName,+ type Principal,+ PrincipalSuccessSchema,+ type RescueEntryFlat,+ type RescueEntryTimeline,+ RescueListSuccessSchema,+ SemanticIndexStatusSchema,+ ServerInfoSuccessSchema,+ WorkspaceSuccessSchema,+} from '@inkeep/open-knowledge-core';+import { z } from 'zod';+import {+ ACP_AGENT_HARNESS_CLIS,+ type AcpHarnessAvailability,+} from '../acp/harness-availability.ts';+import {+ type AcpRegistry,+ type CustomAgentEntry,+ FEATURED_AGENT_IDS,+ registryPlatformKey,+} from '../acp/registry.ts';+import { MAX_ACP_THREADS } from '../acp/thread-manager.ts';+import { getBootTimings } from '../boot-timings.ts';+import { isConfigDoc, isSystemDoc } from '../cc1-broadcast.ts';+import { collabUrlFromRequestHeaders } from '../collab-bootstrap-url.ts';+import { getLocalDir } from '../config/paths.ts';+import { isSupportedDocFile, stripDocExtension } from '../doc-extensions.ts';+import type { DocumentDurabilityState } from '../document-durability-state.ts';+import { deriveDetection, embedProbeRing } from '../embed-probe.ts';+import {+ FileEmbeddingsBackend,+ type ResolvedSemanticConfig,+ resolveEmbeddingsCredential,+ type SemanticSearchService,+} from '../embeddings/index.ts';+import type { FileIndexEntry } from '../file-watcher.ts';+import { type createInstalledAgentsProbe, handleInstalledAgents } from '../handoff-api.ts';+import type { PinoLogger } from '../logger.ts';+import { readServerLock } from '../server-lock.ts';+import { listRescueCheckpoints, type ShadowRef, type TimelineRescueEntry } from '../shadow-repo.ts';+import type { ApiRouteTable } from './api-pipeline.ts';+import { errorResponse } from './error-response.ts';+import { errnoCode } from './handler-utils.ts';+import { getRequestId } from './request-id.ts';+import { withValidation } from './request-validation.ts';+import { successResponse } from './success-response.ts';++export interface ConfigSystemRouteDeps {+ contentDir: string;+ projectDir: string | undefined;+ ephemeral: boolean;+ log: PinoLogger;+ /** Init-completion gate; server-info parks on it before serving branch state. */+ ready: Promise<void> | undefined;+ /** Only `getActiveBranch` is read (server-info); narrowed to it. */+ durabilityState: Pick<DocumentDurabilityState, 'getActiveBranch'>;+ serverInstanceId: string;+ getDiskAckSVs: (() => Record<string, string>) | undefined;+ getCollabClientCount: (() => number) | undefined;+ getConfigDiagnostics: (() => ConfigDiagnosticsReport) | undefined;+ acpRegistry: AcpRegistry | undefined;+ loadAcpCustomAgents: (() => Promise<CustomAgentEntry[]>) | undefined;+ acpHarnessAvailability: () => Promise<AcpHarnessAvailability>;+ /** Route-level peer gate (loopback always passes; `allowExternal` relaxes). */+ isRoutePeerAdmitted: (remoteAddress: string | undefined) => boolean;+ /**+ * The extension's exposure-widened workspace-Host predicate — when the+ * server is exposed, the tunnel's public Host passes alongside the loopback+ * names.+ */+ isAllowedWorkspaceHostHeader: (host: string | undefined) => boolean;+ /** The extension's shared local-op security gate (emits RFC 9457 on refusal). */+ checkLocalOpSecurity: (+ req: IncomingMessage,+ res: ServerResponse,+ opts: { handler: string },+ ) => boolean;+ getPrincipal: (() => Principal | null) | undefined;+ /** Only `getStatus` is read (semantic-status); narrowed to it. */+ semanticSearch: Pick<SemanticSearchService, 'getStatus'> | undefined;+ readSemanticProviderConfig: (() => ResolvedSemanticConfig) | undefined;+ embeddingsSecretsFile: string | undefined;+ getFileIndex: () => ReadonlyMap<string, FileIndexEntry>;+ shadowRef: ShadowRef | undefined;+ getCurrentBranch: (() => string | null) | undefined;+ /** Only `probeAll` is read (installed-agents); narrowed to it. */+ installedAgentsCache: Pick<ReturnType<typeof createInstalledAgentsProbe>, 'probeAll'>;+}++export interface ConfigSystemRoutes {+ /** 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 createConfigSystemRoutes(deps: ConfigSystemRouteDeps): ConfigSystemRoutes {+ const {+ contentDir,+ projectDir,+ ephemeral,+ log,+ ready,+ durabilityState,+ serverInstanceId,+ getDiskAckSVs,+ getCollabClientCount,+ getConfigDiagnostics,+ acpRegistry,+ loadAcpCustomAgents,+ acpHarnessAvailability,+ isRoutePeerAdmitted,+ isAllowedWorkspaceHostHeader,+ checkLocalOpSecurity,+ getPrincipal,+ semanticSearch,+ readSemanticProviderConfig,+ embeddingsSecretsFile,+ getFileIndex,+ shadowRef,+ getCurrentBranch,+ installedAgentsCache,+ } = deps;++ /**+ * GET /api/server-info+ *+ * Returns `{ ok, serverInstanceId, currentBranch, currentDiskAckSVs }`.+ * Called by the client's `ProviderPool` as a boot-time warmup BEFORE+ * any WebSocket provider opens, so the first provider's auth token+ * can carry `expectedServerInstanceId` and `expectedBranch` on the+ * very first connect (avoiding one "null-claim accept → broadcast →+ * populate cache → next connect claim" cycle on cold start).+ *+ * `currentBranch` is the late-join backstop for CC1's `branch-switched`+ * stateless broadcast — disconnected clients reconnecting compare it+ * against their last-observed branch and trigger `handleBranchSwitched`+ * on mismatch (also surfaced as the `expectedBranch` auth-token claim,+ * see `auth-token-schema.ts`). Always populated — `getActiveBranch()`+ * defaults to `'main'` when git is disabled.+ *+ * Gated on `ready` for the same reason `handleDocumentList` is: the+ * boot-time `switchReconciledBaseScope(startupBranch)` lives inside+ * `initAsync` (server-factory.ts), and a renderer that fetches before+ * it runs would observe this server's initial `'main'` default instead of+ * the actual HEAD branch. The renderer's `current-branch-store` is+ * fire-once and only updates from CC1 `branch-switched`, so a stale+ * cold-start fetch sticks until a real cross-branch checkout.+ *+ * `currentDiskAckSVs` is the late-join backstop for the per-doc CC1+ * `disk-ack` channel — same recovery shape as `currentBranch` but the+ * per-doc state vector watermark used by mismatch-recycle baseline-+ * selection. Omitted in dev/plugin mode (no CC1 broadcaster).+ *+ * Gating: protected by the global `/api/*` Origin allowlist (CSRF+ * guard against cross-origin browsers). No-Origin requests (curl,+ * server-to-server, LAN peers using non-browser tooling) pass through+ * — the same posture as the rest of the read-side `/api/*` surface+ * (`/api/documents`, `/api/document`, `/api/pages`, `/api/backlinks`).+ * Disclosure shape: `serverInstanceId` is a per-process random UUID;+ * `currentBranch` matches the workspace's git history; the SV map+ * enumerates the same docName set as `/api/documents` plus per-+ * client Lamport op counts (random clientID, no wall-clock).+ * Single-user-loopback deployment model is documented in+ * `server-factory.ts` near the principalAuthExtension; hosted/multi-+ * tenant deployments must wrap this entire `/api/*` class with+ * authentication and per-caller scoping.+ */+ const handleServerInfo = withValidation(+ EmptyRequestSchema,+ async (_req, res) => {+ try {+ // Park until `initAsync` has called `switchReconciledBaseScope` with+ // the resolved HEAD branch. Without this gate, a renderer that fetches+ // during the boot window reads this server's initial `'main'`+ // default and caches it in `current-branch-store` for the lifetime of+ // the session. Mirrors the `handleDocumentList` gate; `.catch()` keeps+ // the handler responsive on a degraded boot.+ if (ready) {+ await ready.catch((err: unknown) => {+ log.warn(+ { err, handler: 'server-info' },+ '[api] ready gate rejected — responding with current state',+ );+ });+ }+ const currentBranch = durabilityState.getActiveBranch();+ // `getDiskAckSVs` is wired by standalone boot; plugin mode (dev+ // server) doesn't have a CC1Broadcaster and omits the field. The+ // schema's `.optional()` keeps the response shape valid in both+ // cases without a separate "no broadcaster" branch on the client.+ const currentDiskAckSVs = getDiskAckSVs?.();+ // Boot-phase timings (desktop startup instrumentation). Present only+ // when the boot path called `startBootTimings` (standalone `bootServer`);+ // the dev-server / plugin path leaves it `undefined`, so the schema's+ // `.optional()` keeps the response valid. All bounded numbers — safe to+ // disclose (per-process timing, no paths/content).+ const boot = getBootTimings();+ const collabClients = getCollabClientCount?.();+ // `Cache-Control: no-store` matches the disclosure semantics: every+ // field is per-process / per-moment state. A back/forward-cached+ // 304 carrying a stale `currentDiskAckSVs` could silently corrupt+ // the recycle baseline-selection on the next mismatch.+ successResponse(+ res,+ 200,+ ServerInfoSuccessSchema,+ {+ serverInstanceId,+ currentBranch,+ ...(currentDiskAckSVs !== undefined ? { currentDiskAckSVs } : {}),+ ...(boot !== undefined ? { boot } : {}),+ ...(collabClients !== undefined ? { collabClients } : {}),+ },+ {+ handler: 'server-info',+ extraHeaders: { 'Cache-Control': 'no-store' },+ },+ );+ } catch (e) {+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {+ handler: 'server-info',+ cause: e,+ });+ }+ },+ { handler: 'server-info', method: 'GET', skipBodyParse: true },+ );++ const AcpCatalogAgentSchema = z.object({+ id: z.string(),+ name: z.string(),+ version: z.string(),+ description: z.string().optional(),+ license: z.string().optional(),+ iconUrl: z.string().optional(),+ website: z.string().optional(),+ source: z.enum(['registry', 'custom']),+ /** A launchable distribution exists for this host platform. */+ supported: z.boolean(),+ featured: z.boolean(),+ harness: z+ .object({+ cli: z.enum(['claude', 'codex', 'cursor', 'gemini', 'opencode', 'pi']),+ availability: z.enum(['present', 'not-found', 'unknown']),+ /** No `absent` member — see `HarnessCredentials`. */+ credentials: z.enum(['present', 'unknown']),+ })+ .optional(),+ });+ const AcpCatalogSuccessSchema = z.object({+ agents: z.array(AcpCatalogAgentSchema),+ /** True when served from the offline fallback cache. */+ stale: z.boolean(),+ maxThreads: z.number(),+ });++ const handleAcpCatalog = withValidation(+ EmptyRequestSchema,+ async (_req, res) => {+ if (acpRegistry === undefined) {+ errorResponse(res, 404, 'urn:ok:error:not-found', 'ACP catalog unavailable.', {+ handler: 'acp-catalog',+ });+ return;+ }+ try {+ const platform = registryPlatformKey();+ const { agents, stale } = await acpRegistry.getCatalog();+ const custom = (await loadAcpCustomAgents?.()) ?? [];+ const harnessAvailability = await acpHarnessAvailability();+ const rows = [+ ...agents.map((a) => {+ const harnessCli = ACP_AGENT_HARNESS_CLIS[a.id];+ return {+ id: a.id,+ name: a.name,+ version: a.version,+ ...(a.description !== undefined ? { description: a.description } : {}),+ ...(a.license !== undefined ? { license: a.license } : {}),+ ...(a.icon !== undefined ? { iconUrl: a.icon } : {}),+ ...(a.website !== undefined ? { website: a.website } : {}),+ source: 'registry' as const,+ supported:+ a.distribution.npx !== undefined ||+ a.distribution.uvx !== undefined ||+ (platform !== null && a.distribution.binary?.[platform] !== undefined),+ featured: FEATURED_AGENT_IDS.includes(a.id),+ ...(harnessCli !== undefined+ ? {+ harness: {+ cli: harnessCli,+ availability: harnessAvailability[harnessCli]?.availability ?? 'unknown',+ credentials: harnessAvailability[harnessCli]?.credentials ?? 'unknown',+ },+ }+ : {}),+ };+ }),+ ...custom.map((c: CustomAgentEntry) => ({+ id: c.id,+ name: c.name,+ version: 'custom',+ source: 'custom' as const,+ supported: true,+ featured: false,+ })),+ ];+ successResponse(+ res,+ 200,+ AcpCatalogSuccessSchema,+ { agents: rows, stale, maxThreads: MAX_ACP_THREADS },+ { handler: 'acp-catalog', extraHeaders: { 'Cache-Control': 'no-store' } },+ );+ } catch (e) {+ errorResponse(+ res,+ 502,+ 'urn:ok:error:registry-unreachable',+ 'Agent registry unreachable.',+ {+ handler: 'acp-catalog',+ cause: e,+ },+ );+ }+ },+ { handler: 'acp-catalog', method: 'GET', skipBodyParse: true },+ );++ async function handlePrincipal(req: IncomingMessage, res: ServerResponse): Promise<void> {+ // Loopback + Host-header gate. The principal record discloses operator+ // PII — `display_name` (real name) and `display_email` — sourced from+ // local `git config`. Under `--host 0.0.0.0` (demos, shared dev boxes,+ // Codespaces) this would otherwise be readable by any LAN peer or+ // cross-origin page that bypasses the Origin allowlist (non-browser+ // callers send no `Origin` header). Matches the same gate+ // `handleMetricsAgentPresence` and `handleWorkspace` apply.+ // Authorization runs BEFORE method dispatch so a bad Host never leaks+ // "verb the endpoint expects" via the 405 response (OWASP ASVS V4.1.1).+ if (!isRoutePeerAdmitted(req.socket.remoteAddress)) {+ errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {+ handler: 'principal',+ });+ return;+ }+ if (!isAllowedWorkspaceHostHeader(req.headers.host)) {+ errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {+ handler: 'principal',+ });+ return;+ }+ if (req.method !== 'GET') {+ errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {+ handler: 'principal',+ extraHeaders: { Allow: 'GET' },+ });+ return;+ }+ const principal = getPrincipal?.() ?? null;+ if (!principal) {+ errorResponse(res, 404, 'urn:ok:error:principal-not-available', 'Principal not available.', {+ handler: 'principal',+ });+ return;+ }+ successResponse(res, 200, PrincipalSuccessSchema, principal, { handler: 'principal' });+ }++ async function handleEmbedDetect(req: IncomingMessage, res: ServerResponse): Promise<void> {+ // Diagnostic endpoint for the Cursor / Codex / Claude Code embedded-viewer+ // detection spikes. Reads from the in-process ring buffer populated in+ // `onRequest` and surfaces boolean signals derived from the most recent+ // entry's UA. Loopback + Host-header gated — same pattern as+ // `handlePrincipal` / `handleMetricsAgentPresence`. Disclosed fields+ // (full request headers, remote address) are local-editing-only signals.+ if (!isRoutePeerAdmitted(req.socket.remoteAddress)) {+ errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {+ handler: 'embed-detect',+ });+ return;+ }+ if (!isAllowedWorkspaceHostHeader(req.headers.host)) {+ errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {+ handler: 'embed-detect',+ });+ return;+ }+ if (req.method !== 'GET') {+ errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {+ handler: 'embed-detect',+ extraHeaders: { Allow: 'GET' },+ });+ return;+ }+ const entries = embedProbeRing.read();+ successResponse(+ res,+ 200,+ EmbedDetectSuccessSchema,+ {+ entries,+ count: entries.length,+ detection: deriveDetection(entries[0]),+ },+ { handler: 'embed-detect' },+ );+ }++ async function handleWorkspace(req: IncomingMessage, res: ServerResponse): Promise<void> {+ // Authorization runs BEFORE method dispatch: reversing the order turns the+ // method check into a fingerprinting oracle for unauth callers (GET → 403,+ // POST → 405 discloses the verb the endpoint expects). See OWASP ASVS 4.0+ // V4.1.1 — "perform access control on every request."+ //+ // Loopback-only: this endpoint discloses the absolute host filesystem path+ // (including home directory / username). That's fine for the local-editing+ // use case the rest of the API is designed for, but if the user configures+ // `server.host: 0.0.0.0` (demos, shared dev boxes, Codespaces), we do NOT+ // want to leak the host shape over the network or to cross-origin fetches.+ // All loopback clients (including requests from a browser on the same+ // machine) pass — connections from other interfaces are refused.+ //+ // DNS-rebinding defense: `req.socket.remoteAddress` will read `127.0.0.1`+ // for any request that reached the socket via loopback, including requests+ // triggered by a malicious page that rebinds its hostname to `127.0.0.1`.+ // The Host-header allowlist below enforces that the caller actually spoke+ // to us via `localhost` / `127.0.0.1` / `[::1]`, matching the mitigation+ // in the Ethereum/geth JSON-RPC lineage. Same-origin fetches from the+ // editor app pass; cross-origin rebinding attempts are refused.+ if (!isRoutePeerAdmitted(req.socket.remoteAddress)) {+ errorResponse(res, 403, 'urn:ok:error:loopback-required', 'Loopback required.', {+ handler: 'workspace',+ });+ return;+ }+ if (!isAllowedWorkspaceHostHeader(req.headers.host)) {+ errorResponse(res, 403, 'urn:ok:error:host-not-allowed', 'Host header not allowed.', {+ handler: 'workspace',+ });+ return;+ }+ if (req.method !== 'GET') {+ errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {+ handler: 'workspace',+ extraHeaders: { Allow: 'GET' },+ });+ return;+ }+ // Absolute, canonical contentDir so the client can build full filesystem+ // paths (e.g. for the sidebar 'Copy path > Full path' action). Symlinks in+ // the workspace root are resolved via realpath so the path matches on-disk+ // truth. We treat error kinds in line with the persistence layer's symlink+ // contract:+ // - ENOENT: contentDir missing on disk → 200 with `symlinkResolved: false`+ // and the unresolved path. Lets "Copy Path" still produce a meaningful+ // value when the directory was deleted between server start and this+ // request; the client decides whether to act on it.+ // - ELOOP / EACCES / anything else: real filesystem error → 500. Matches+ // persistence's stricter policy (cyclic symlinks are rejected+ // everywhere) and avoids handing the user a path that won't resolve.+ const resolvedRoot = resolve(contentDir);+ let resolvedContentDir = resolvedRoot;+ let symlinkResolved = true;+ try {+ resolvedContentDir = realpathSync(resolvedRoot);+ } catch (err) {+ const code = errnoCode(err);+ if (code === 'ENOENT') {+ log.warn(+ { path: resolvedRoot },+ '[workspace] contentDir does not exist; returning unresolved path',+ );+ symlinkResolved = false;+ } else {+ log.warn({ path: resolvedRoot, err }, '[workspace] realpath failed for contentDir');+ errorResponse(+ res,+ 500,+ 'urn:ok:error:internal-server-error',+ 'Workspace realpath failed.',+ { handler: 'workspace', detail: code ?? undefined, cause: err },+ );+ return;+ }+ }+ // `pathSeparator` lets the client build full paths without guessing from+ // the shape of `contentDir` (which breaks on Windows + forward-slash paths+ // and on POSIX folders that contain a literal backslash in the name).+ successResponse(+ res,+ 200,+ WorkspaceSuccessSchema,+ {+ contentDir: resolvedContentDir,+ pathSeparator: sep,+ symlinkResolved,+ },+ { handler: 'workspace' },+ );+ }++ async function handleInstalledAgentsRoute(+ req: IncomingMessage,+ res: ServerResponse,+ ): Promise<void> {+ // Loopback + DNS-rebinding gate. Same contract the rest of the host-+ // disclosure surface uses (`/api/workspace`, every `/api/local-op/*`) —+ // this endpoint discloses a stable OS-level fingerprint of which AI+ // agents are installed, readable without preflight under the permissive+ // `Access-Control-Allow-Origin: *` that `/api/*` sets. Gating on+ // `checkLocalOpSecurity` confines the fingerprint to same-machine,+ // same-origin callers (the editor UI) and refuses cross-origin browser+ // contexts + DNS-rebinding attempts that would otherwise succeed.+ // `checkLocalOpSecurity` itself emits RFC 9457 problem+json on rejection.+ if (!checkLocalOpSecurity(req, res, { handler: 'installed-agents' })) return;+ try {+ await handleInstalledAgents(req, res, installedAgentsCache.probeAll);+ } catch (e) {+ // Defensive: `handleInstalledAgents` catches internally, so this only+ // fires on truly unexpected throws (e.g., probeAll synchronously+ // throwing before its internal try/catch). Guard `headersSent` so we+ // don't double-emit if the inner handler already wrote a response.+ if (!res.headersSent) {+ log.error(+ { err: e, requestId: getRequestId(req) },+ '[installed-agents] route wrapper failed',+ );+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {+ handler: 'installed-agents',+ cause: e,+ });+ }+ }+ }++ // `/api/config` — collab-bootstrap payload for the React shell. This server+ // serves the SPA itself, so the shell fetches `/api/config` from the same+ // origin (api-config.ts consumes it; the `--only ui` split-mode proxy in+ // `packages/cli` emits the same shape): GET returns+ // `{collabUrl, previewUrl, port}`. GET+ // stays open like the other read-only bootstrap endpoints+ // (document/pages/backlinks) — it carries no PII and only reflects the+ // client's own Host back to itself. `lockDir` is the project's+ // `.ok/local/` (the server-lock anchor); null when projectDir is unconfigured+ // (some test harnesses), leaving collabUrl bootstrap intact.+ const lockDir = projectDir ? getLocalDir(projectDir) : null;+ async function handleApiConfig(req: IncomingMessage, res: ServerResponse): Promise<void> {+ if (req.method === 'GET' || req.method === 'HEAD') {+ try {+ // Same-origin collab WS: the shell loaded from this server, so+ // `ws(s)://<host>/collab` reaches the same process the request arrived+ // on (scheme honors X-Forwarded-Proto — see collab-bootstrap-url.ts).+ // Avoids the cross-port WS attempt sandboxed preview panes refuse. The+ // Host value is the client's own header reflected back to itself (the+ // Origin CORS gate in `onRequest` already refused cross-origin+ // browsers); it is not independently vetted here. A genuinely absent+ // Host yields a null collabUrl — a deliberate divergence from the+ // split-mode UI proxy's+ // `?? localhost:${resolvedPort}` fallback: this server has no single+ // canonical advertised port to substitute, and the client falls back+ // to a same-origin WS URL on a null. Node HTTP/1.1 always populates+ // Host, so the null path is a malformed-request floor, not a normal case.+ const collabUrl = collabUrlFromRequestHeaders(req.headers);+ const port = lockDir ? (readServerLock(lockDir)?.port ?? 0) : 0;+ // `singleFile` tells the React shell to drop project chrome for an+ // ephemeral single-file session (`ok <file>`).+ const payload = { collabUrl, previewUrl: null, port, singleFile: ephemeral };+ // HEAD carries the same headers but no body; `successResponse` always+ // writes a body, so the no-body verb stays a manual emit.+ if (req.method === 'HEAD') {+ res.setHeader('Content-Type', 'application/json');+ res.setHeader('Cache-Control', 'no-store');+ res.setHeader('X-Content-Type-Options', 'nosniff');+ res.statusCode = 200;+ res.end();+ return;+ }+ successResponse(res, 200, ApiConfigSuccessSchema, payload, {+ handler: 'api-config',+ extraHeaders: { 'Cache-Control': 'no-store' },+ });+ } catch (e) {+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {+ handler: 'api-config',+ cause: e,+ });+ }+ return;+ }+ errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {+ handler: 'api-config',+ extraHeaders: { Allow: 'GET, HEAD' },+ });+ }++ // `/api/config/diagnostics` — active config diagnostics across the user,+ // committed-project, and project-local layers. Read-only and open like+ // `/api/config`: the collector reads the files fresh per request (so a+ // hand-edit or `ok config migrate` is reflected without a restart) and+ // returns only structural findings — scope, file, key path, code, redirect —+ // never a raw config value. `no-store` so a poll always sees current disk+ // state.+ async function handleConfigDiagnostics(req: IncomingMessage, res: ServerResponse): Promise<void> {+ if (req.method === 'GET' || req.method === 'HEAD') {+ try {+ const payload = getConfigDiagnostics?.() ?? { diagnostics: [] };+ // HEAD mirrors GET's headers with no body; `successResponse` always+ // writes one, so the no-body verb stays a manual emit.+ if (req.method === 'HEAD') {+ res.setHeader('Content-Type', 'application/json');+ res.setHeader('Cache-Control', 'no-store');+ res.setHeader('X-Content-Type-Options', 'nosniff');+ res.statusCode = 200;+ res.end();+ return;+ }+ successResponse(res, 200, ConfigDiagnosticsReportSchema, payload, {+ handler: 'api-config-diagnostics',+ extraHeaders: { 'Cache-Control': 'no-store' },+ });+ } catch (e) {+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {+ handler: 'api-config-diagnostics',+ cause: e,+ });+ }+ return;+ }+ errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {+ handler: 'api-config-diagnostics',+ extraHeaders: { Allow: 'GET, HEAD' },+ });+ }++ /**+ * GET /api/semantic-status — read-only setup/coverage probe for the Settings+ * UI. Reports the project-local `enabled` flag, `keyPresent` / `keySource`+ * (an API key is resolvable — a free file/env read), `ready` (has the service+ * warmed yet), `capable` (warmed AND a usable key found), and indexed coverage+ * (embedded / total embeddable pages). Side-effect-free: NO embed, NO egress,+ * NO warm (warming reads the key and — under the legacy keychain backend —+ * could prompt). Returns an inert all-false/zero shape when the service is+ * absent (dev/plugin mode).+ */+ const handleSemanticStatus = withValidation(+ EmptyRequestSchema,+ async (_req, res) => {+ try {+ // Report the service's CURRENT known state — do NOT call ensureWarm()+ // (warming hydrates the cache; a read-only status GET shouldn't). `ready`+ // stays false until the first real search warms it.+ let enabled = false;+ let ready = false;+ let capable = false;+ let embedded = 0;+ if (semanticSearch) {+ const status = semanticSearch.getStatus();+ enabled = status.enabled;+ ready = status.ready;+ capable = status.capable;+ embedded = status.embeddedCount;+ }+ // Resolve the SAME credential the embedder would, for this project ++ // its configured endpoint, so status can't disagree with the real path.+ // A free, prompt-free file/env read — no warm, no egress. The key itself+ // is never returned; only `keyHint` (redacted last-4) so the UI can show+ // WHICH key is set. `keyNotRequired` marks a loopback endpoint that needs+ // no key at all, so the UI doesn't nag a keyless Ollama/LM Studio user.+ const statusConfig = readSemanticProviderConfig?.();+ const statusBaseUrl = statusConfig?.baseUrl ?? DEFAULT_EMBEDDINGS_BASE_URL;+ const cred = await resolveEmbeddingsCredential(+ new FileEmbeddingsBackend(embeddingsSecretsFile),+ projectDir ?? contentDir,+ statusBaseUrl,+ );+ const keyPresent = cred.apiKey !== null;+ const keyNotRequired = !keyPresent && cred.keyless;+ const keySource: 'project' | 'file' | 'env' | null = keyPresent+ ? (cred.source as 'project' | 'file' | 'env')+ : null;+ // Last 4 chars only, and only when the key is long enough that those 4 are+ // a negligible fraction (real provider keys are 40+ chars); never the key.+ const keyHint = cred.apiKey && cred.apiKey.length >= 8 ? cred.apiKey.slice(-4) : null;+ // Total embeddable pages = the same filtered set the search corpus uses.+ let total = 0;+ for (const [docName] of getFileIndex()) {+ if (!isSystemDoc(docName) && !isConfigDoc(docName) && !isHiddenDocName(docName)) {+ total += 1;+ }+ }+ successResponse(+ res,+ 200,+ SemanticIndexStatusSchema,+ {+ enabled,+ keyPresent,+ keyNotRequired,+ keySource,+ keyHint,+ ready,+ capable,+ embedded,+ total,+ },+ { handler: 'semantic-status', extraHeaders: { 'Cache-Control': 'no-store' } },+ );+ } catch (e) {+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {+ handler: 'semantic-status',+ cause: e,+ });+ }+ },+ { handler: 'semantic-status', method: 'GET', skipBodyParse: true },+ );++ /** 24h in milliseconds — rescue buffers older than this are excluded/cleaned. */+ const RESCUE_MAX_AGE_MS = 24 * 60 * 60 * 1000;++ const handleRescueList = withValidation(+ EmptyRequestSchema,+ async (_req, res) => {+ try {+ if (!shadowRef?.current) {+ // No shadow repo configured = no rescue buffers; emit empty list (success).+ successResponse(res, 200, RescueListSuccessSchema, [], { handler: 'rescue-list' });+ return;+ }++ const now = Date.now();+ // `source: 'flat'` rows came from the shutdown-flush path (retained flat-+ // file); `source: 'timeline'` rows came from reconcile-delete /+ // branch-switch (migrated to saveInMemoryCheckpoint). Clients+ // can treat both as interchangeable unless they need the checkpoint sha.+ const entries: (RescueEntryFlat | (RescueEntryTimeline & TimelineRescueEntry))[] = [];++ const rescueDir = resolve(shadowRef.current.gitDir, 'rescue');+ if (existsSync(rescueDir)) {+ try {+ const files = readdirSync(rescueDir).filter((f) => isSupportedDocFile(f));+ for (const file of files) {+ const filePath = resolve(rescueDir, file);+ const stat = statSync(filePath);+ const age = now - stat.mtimeMs;++ if (age > RESCUE_MAX_AGE_MS) {+ try {+ unlinkSync(filePath);+ } catch (e) {+ log.debug({ err: e }, '[rescue] cleanup failed (non-critical)');+ }+ continue;+ }++ entries.push({+ docName: stripDocExtension(file),+ timestamp: stat.mtime.toISOString(),+ size: stat.size,+ source: 'flat',+ });+ }+ } catch (err) {+ log.error({ err }, '[rescue] Failed to list flat-file rescue buffers');+ }+ }++ // Timeline-ref source — merged in so the unified response surfaces all+ // three rescue classes once the write migration ships.+ try {+ const branch = getCurrentBranch?.() ?? 'main';+ const timelineEntries = await listRescueCheckpoints(shadowRef.current, branch);+ for (const t of timelineEntries) {+ entries.push({ ...t, source: 'timeline' });+ }+ } catch (err) {+ log.error({ err }, '[rescue] Failed to list timeline-ref rescue checkpoints');+ }++ successResponse(res, 200, RescueListSuccessSchema, entries, { handler: 'rescue-list' });+ } catch (e) {+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {+ handler: 'rescue-list',+ cause: e,+ });+ }+ },+ { handler: 'rescue-list', method: 'GET', skipBodyParse: true },+ );++ const routes: Record<string, (req: IncomingMessage, res: ServerResponse) => Promise<void>> = {+ '/api/config': handleApiConfig,+ '/api/config/diagnostics': handleConfigDiagnostics,+ '/api/server-info': handleServerInfo,+ '/api/principal': handlePrincipal,+ '/api/workspace': handleWorkspace,+ '/api/semantic-status': handleSemanticStatus,+ '/api/acp/catalog': handleAcpCatalog,+ '/api/installed-agents': handleInstalledAgentsRoute,+ '/api/__embed-detect': handleEmbedDetect,+ '/api/rescue': handleRescueList,+ };++ const table: ApiRouteTable = {+ resolve(url) {+ const handler = routes[url];+ if (handler) {+ return { template: url, dispatch: (req, res) => handler(req, res) };+ }+ return null;+ },+ // `isMutating` tracks legacy MUTATING_ROUTES membership, NOT actual side+ // effects: none of these paths were in that set at the merge base, so the+ // declaration is byte-faithful even though `GET /api/rescue` unlinks+ // rescue buffers older than 24h. The four gated endpoints (principal,+ // workspace, installed-agents, __embed-detect) enforce loopback + Host /+ // local-op INLINE, before method dispatch (gate-before-405) — a different+ // contract from the pipeline's mutating gate, so they do not migrate onto it.+ isMutating: () => false,+ };++ return {+ paths: Object.keys(routes),+ table,+ };+}diff --git a/packages/server/src/http/history-routes.ts b/packages/server/src/http/history-routes.tsnew file mode 100644index 000000000..6a5e2af68--- /dev/null+++ b/packages/server/src/http/history-routes.ts@@ -0,0 +1,387 @@+/**+ * The version-history read family — `history` plus the dynamic+ * `history/:sha` prefix — the sixth natively-routed Wave 2 group and the+ * SECOND to carry a DYNAMIC legacy prefix (`link-graph-routes.ts`'s+ * `/api/tags/:name` was the first). Same lift shape as the earlier groups:+ * what the handlers closed over in the extension arrives as+ * {@link HistoryRouteDeps}, the handler bodies are unchanged, and the extension+ * composes this group's table into its `nativeApi` handle while the legacy+ * dispatch record (and its `/api/history/` resolve fall-through) lose the paths+ * in the same change.+ *+ * The dynamic `/api/history/:sha` leg follows the `/api/tags/:name` precedent+ * in `link-graph-routes.ts`: a Hono `/api/history/*` wildcard preserves the+ * legacy URL template and its edge-case statuses. The two diverge on malformed+ * input by design — `tags` returns a typed 400, while here the table's+ * `resolve` decodes the sha inside `dispatch` so a malformed encoding surfaces+ * as the dispatch span's generic 500 (the legacy behavior), because byte parity+ * with the lifted handler outranks modernization for the lift. `/api/rollback`+ * mutates and stays on the legacy MUTATING_ROUTES gate.+ */++import type { IncomingMessage, ServerResponse } from 'node:http';+import {+ EmptyRequestSchema,+ HistorySuccessSchema,+ HistoryVersionSuccessSchema,+} from '@inkeep/open-knowledge-core';+import { getLogger, type PinoLogger } from '../logger.ts';+import {+ createAncestorShaSetCache,+ getOrLoadRenameLogIndex,+ 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;+ /** Drains OK-artifact (contributor) stragglers before a history read. */+ commitOkArtifactWrite: (context: string) => Promise<void>;+ getCurrentBranch: (() => string | null) | undefined;+ /** The extension's folder-path validator, shared with folder-config/template. */+ validateFolderRel: (+ raw: string,+ res: ServerResponse,+ label?: 'path' | 'folder',+ handler?: string,+ ) => { folderRel: string; resolvedContentDir: string } | null;+ /** Traversal-safe docName → git pathspec guard (shared module helper). */+ safeDocPath: (docName: string, contentRoot: string) => { path: string } | { error: string };+ /** Historical tree-path candidates for a docName (shared module helper). */+ docTreePathCandidates: (docName: string, contentRoot: string) => readonly string[];+}++export interface HistoryRoutes {+ /** 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 createHistoryRoutes(deps: HistoryRouteDeps): HistoryRoutes {+ const {+ contentRoot,+ log,+ shadowRef,+ flushGitCommit,+ commitOkArtifactWrite,+ getCurrentBranch,+ validateFolderRel,+ safeDocPath,+ docTreePathCandidates,+ } = deps;++ // Single-flight dedupe for `GET /api/history`. Keyed by the+ // full normalized query tuple (mode + branch + every param each mode reads),+ // so N concurrent identical history requests share ONE git walk and N+ // identical responses. Per-server-instance, same rationale as showAllInflight.+ const historyInflight = createSingleFlight<Awaited<ReturnType<typeof getDocumentHistory>>>();++ const handleHistory = withValidation(+ EmptyRequestSchema,+ async (req, res) => {+ const shadow = shadowRef?.current;+ if (!shadow) {+ // 503 (not 400): shadow-repo unavailability is a server-side state,+ // matching the sync-not-active precedent.+ errorResponse(+ res,+ 503,+ 'urn:ok:error:shadow-not-configured',+ 'Shadow repo not configured.',+ { handler: 'history' },+ );+ return;+ }++ // Read-your-writes: agent write handlers no longer force an L2 shadow+ // commit per write (they ride the persistence debounce), so drain any+ // pending commit before querying — a `history` call issued right after a+ // write must list that write. No-op when nothing is pending. The flush+ // blocks the response, so surface slow (cold-index) drains in the logs.+ try {+ const flushStart = performance.now();+ await flushGitCommit?.();+ // Contributor stragglers too: lifecycle writes flush fire-and-forget+ // now, so a contributor recorded after an in-flight run snapshotted+ // the map is not in the drained commit — without this second drain the+ // just-made version is missing from the timeline. Reader-side on+ // purpose: draining in the generic flush changed shutdown semantics.+ 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 (branch.includes('..') || !/^[a-zA-Z0-9][a-zA-Z0-9._/-]*$/.test(branch)) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid branch name.', {+ handler: 'history',+ });+ return;+ }++ // Folder timeline — attributed activity over a folder's+ // `.ok/` artifacts (templates + frontmatter). Distinct from the doc DAG+ // walk: no rename chain, no checkpoint filter.+ if (folderParam !== null && !docName) {+ const validated = validateFolderRel(folderParam, res, 'folder', 'history');+ 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);+ // Single-flight key — folder mode. The resolved `branch` (not the raw+ // param) is used so two requests on the same effective branch coalesce.+ const folderKey = `folder\0${branch}\0${validated.folderRel}\0${folderLimit}\0${folderOffset}`;+ // `getFolderTimeline` is self-contained: it catches its own git/IO+ // errors, logs them, and returns an empty result rather than throwing —+ // so a handler-level catch here would be dead code.+ 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;+ }++ // Validate docName before it reaches `getDocumentHistory`, which+ // interpolates it into a git pathspec for `git log` / `cat-file -e`.+ // Without this guard, a docName containing `..` or null bytes could+ // (after git's pathspec normalization) target a path outside the+ // configured content root in the shadow repo. Sibling endpoints+ // (handleHistoryVersion, handleDiff, handleRollback) already gate via+ // safeDocPath.+ 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;+ // Auto-consolidation checkpoints are hidden by default; opt-in for+ // debugging / a future maintenance UI. Part of the single-flight tuple+ // because it changes the result set.+ const includeAutoCheckpoints = url.searchParams.get('includeAutoCheckpoints') === 'true';++ // Single-flight key — doc mode. Covers every param `getDocumentHistory`+ // reads so a differing tuple never shares a wrong result.+ 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) {+ // Generic title — raw `e.message` can leak FS paths / library internals.+ // The underlying message is forwarded to Pino via `cause` for ops triage.+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to read history.', {+ handler: 'history',+ cause: e,+ });+ }+ },+ { handler: 'history', method: 'GET', skipBodyParse: true },+ );++ // ── GET /api/history/:sha ─────────────────────────────────────────────────+ 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) {+ // 503 (not 400): shadow-repo unavailability is a server-side state,+ // matching the sync-not-active precedent.+ 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';++ // Validate SHA format+ if (!/^[0-9a-f]{40}$/i.test(sha)) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid commit SHA.', {+ handler: 'history-version',+ });+ return;+ }++ try {+ // Resolve the doc's historical path at this commit by walking the+ // rename chain (mirrors handleRollback + handleDiff). Without+ // this, requesting a pre-rename commit's content returns 404 even+ // though the timeline correctly shows the entry — the UI then falls+ // back to its "Diff unavailable" / "Document did not exist" rendering.+ 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}`);++ // Resolve commit metadata+ 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',+ // Decode inside dispatch so a malformed encoding surfaces as the+ // dispatch span's generic 500 (the legacy behavior), not a+ // resolve-time throw.+ dispatch: encodedSha+ ? async (req, res) => {+ await handleHistoryVersion(req, res, decodeURIComponent(encodedSha));+ }+ : undefined,+ };+ }+ return null;+ },+ // `isMutating` tracks legacy MUTATING_ROUTES membership, NOT actual side+ // effects: neither route was in that set at the merge base, so the+ // declaration is byte-faithful even though `GET /api/history` flushes a+ // pending git commit + drains contributor stragglers. `/api/rollback`+ // mutates and stays on the legacy gate in the extension.+ isMutating: () => false,+ };++ return {+ // `/api/history/*` (not `:sha`) so an empty or slash-containing tail+ // reaches the table exactly like the legacy prefix match did.+ paths: [...Object.keys(routes), '/api/history/*'],+ table,+ };+}diff --git a/packages/server/src/http/lint-routes.ts b/packages/server/src/http/lint-routes.tsnew file mode 100644index 000000000..e833f96d3--- /dev/null+++ b/packages/server/src/http/lint-routes.ts@@ -0,0 +1,506 @@+/**+ * The lint + audit read family — `lint/config`, `lint/frontmatter-schemas`,+ * `lint`, `lint/audit`, `audit` — the fifth natively-routed Wave 2 group. The+ * editor reads the effective lint config through `lint/config`; the Settings+ * GUI's write side (native `.markdownlint.*` rules) stays in the extension. Same+ * lift shape as `link-graph-routes.ts` / `metrics-routes.ts` /+ * `document-routes.ts` / `config-system-routes.ts`: what the handlers closed+ * over in the extension arrives as {@link LintRouteDeps}, the handler bodies+ * are unchanged, and the extension composes this group's table into its+ * `nativeApi` handle while the legacy dispatch record loses the paths in the+ * same change.+ *+ * The write-side lint routes (`lint/markdownlint-config`,+ * `lint/frontmatter-schema`, `lint/fix`) ride the legacy MUTATING_ROUTES gate+ * and stay in the extension; they share `unmatchedGlobProblems` and+ * `readAuditGeneration` (the config-epoch reader coupled to the lint-config CC1+ * emitter), which therefore arrive here as deps rather than moving. The+ * per-server audit cache + single-flight are read-only-owned, so they move into+ * this group.+ */++import type { IncomingMessage, ServerResponse } from 'node:http';+import { isAbsolute, relative, resolve } from 'node:path';+import type { Hocuspocus } from '@hocuspocus/server';+import {+ DEFAULT_LINTER_CONFIG,+ type DocumentListEntry,+ EmptyRequestSchema,+ FrontmatterSchemasListSuccessSchema,+ isFrontmatterSchemaAsset,+ type LinksValidationSetting,+ LintAuditResponseSchema,+ LintConfigResponseSchema,+ LintDocResultSchema,+ type LinterConfig,+ summarizeLintPluginFailures,+ ValidationAuditCountsResponseSchema,+ ValidationAuditResponseSchema,+} from '@inkeep/open-knowledge-core';+import { SymlinkEscapeError } from '../apply-managed-rename.ts';+import type { ContentFilter } from '../content-filter.ts';+import type { DerivedDocumentIndexApiPort } from '../derived-document-index.ts';+import { AuditSupersededError, auditProject, lintDoc } from '../lint/audit.ts';+import { AuditCache } from '../lint/audit-cache.ts';+import { listProjectSchemaFiles, SCHEMA_LIST_CAP } from '../lint/frontmatter-schemas.ts';+import {+ composeEffectiveLinterConfig,+ composeFrontmatterSchemasConfig,+ resolveNativeConfigForDoc,+} from '../lint/resolve-config.ts';+import {+ createProjectValidators,+ type ProjectValidator,+ runValidationAudit,+ toValidationCountsPlane,+ type ValidationAuditResult,+} from '../lint/validation-audit.ts';+import { createSingleFlight } from '../single-flight.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 LintRouteDeps {+ hocuspocus: Hocuspocus;+ contentDir: string;+ projectDir: string | undefined;+ contentFilter: ContentFilter | undefined;+ /** The extension's docName safety predicate (path-traversal refusal). */+ isSafeDocName: (docName: string) => boolean;+ /** docName → traversal-confined content-relative file path (null on refusal). */+ resolveDocFilePath: (contentDir: string, docName: string) => string | null;+ /** Rejects absolute / traversing scope params before they reach the walker. */+ isValidRelativeContentPath: (path: string) => boolean;+ /** The extension's Show All Files walker (schema-file discovery consumes it). */+ streamShowAllEntries: (opts: {+ contentDir: string;+ contentFilter: ContentFilter;+ dirFilter: string | null;+ maxEntries: number;+ }) => AsyncGenerator<DocumentListEntry, { truncated: boolean }, void>;+ getLinterBaseConfig: (() => LinterConfig) | undefined;+ getLinksValidationSetting: (() => LinksValidationSetting) | undefined;+ derivedDocumentIndex: DerivedDocumentIndexApiPort | undefined;+ collectAdmittedDocNames: () => Promise<Set<string>>;+ /**+ * Zero-match `appliesTo` detection over the project doc list — shared with+ * the write-side lint handlers that stay in the extension.+ */+ unmatchedGlobProblems: (effective: LinterConfig) => string[];+ /**+ * The lint-config epoch + branch + local-target generation reader — coupled+ * to the extension's `signalLintConfigChanged` CC1 emitter, so it stays there+ * and arrives here as a dep.+ */+ readAuditGeneration: () => string;+}++export interface LintRoutes {+ /** 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 createLintRoutes(deps: LintRouteDeps): LintRoutes {+ const {+ hocuspocus,+ contentDir,+ projectDir,+ contentFilter,+ isSafeDocName,+ resolveDocFilePath,+ isValidRelativeContentPath,+ streamShowAllEntries,+ getLinterBaseConfig,+ getLinksValidationSetting,+ derivedDocumentIndex,+ collectAdmittedDocNames,+ unmatchedGlobProblems,+ readAuditGeneration,+ } = deps;++ /**+ * Live CRDT source for a currently-loaded doc, else null. Lint reads must+ * see the same bytes the editor and `/api/lint/fix` operate on: the disk+ * file lags the CRDT behind the persistence debounce, and if a flush is+ * ever lost the two diverge durably — a disk-only audit then reports+ * problems the live doc no longer has and the Fix all sweep no-ops forever.+ * Unloaded docs have no live copy; disk is authoritative for them.+ */+ const liveLintSourceFor = (docRelPath: string): string | null => {+ const docName = docRelPath.replace(/\.(md|mdx)$/i, '');+ const doc = hocuspocus.documents.get(docName);+ return doc === undefined ? null : doc.getText('source').toString();+ };++ // One cache per server instance (not module-scoped): its keys carry contentDir,+ // but a per-server lifetime also means a restart starts cold, which is the+ // right blast radius for a disk-stamp-keyed cache.+ const auditCache = new AuditCache();+ /**+ * Audits in flight, keyed by scope + config fingerprint. Every window runs the+ * freshness triggers independently, and the Problems panel can refresh at the+ * same moment, so a single config change can ask for the same whole-project+ * walk several times over. Coalescing makes them one walk instead of N cold+ * ones that each finish too late to warm the others' cache.+ *+ * The walk yields to the event loop, so a request issued after a config+ * mutation or a branch switch IS parsed while an earlier walk is still+ * running and could attach to it. The fingerprint alone would not stop that:+ * it covers the BASE config, which never carries markdownlint `rules` (those+ * come from the native `.markdownlint.*` cascade) nor frontmatter-schema+ * bodies, and says nothing at all about which branch's content is on disk.+ * {@link readAuditGeneration} is what makes the key move, which is why it is+ * read here per request rather than captured once. The per-file cache keys on+ * the fully-resolved config and the file's disk stamp, so nothing is cached+ * under the wrong rules or the wrong branch's bytes either way.+ */+ const auditFlight = createSingleFlight<ValidationAuditResult>();++ function runCoalescedAudit(+ validators: readonly ProjectValidator[],+ targetPath: string | undefined,+ configFingerprint: string,+ ): Promise<ValidationAuditResult> {+ const key = `${configFingerprint} ${readAuditGeneration()} ${targetPath ?? ''}`;+ return auditFlight.run(key, () => runValidationAudit(validators, { targetPath })).promise;+ }++ /**+ * A superseded walk has no plane to report, so the caller gets a retryable+ * 409 rather than a stale or mixed one. The store-side effect is exactly the+ * effect of any failed audit — previous entries stand — and whichever change+ * superseded this walk has already broadcast its own CC1 channel+ * (`lint-config` for a config mutation, `branch-switched` for a switch), so+ * the corrective walk is scheduled without the caller doing anything.+ */+ function respondAuditSuperseded(res: ServerResponse, handler: string): void {+ errorResponse(+ res,+ 409,+ 'urn:ok:error:audit-superseded',+ 'The lint configuration or branch changed while the audit was running; re-run it.',+ { handler },+ );+ }++ const handleGetLintConfig = withValidation(+ EmptyRequestSchema,+ async (req, res) => {+ try {+ // A `?doc=` is accepted (the editor passes the active doc) but the+ // effective config resolves per doc (cli2 cascade: nearest native+ // file on the doc→root walk governs); no `?doc=` → root-level.+ const url = new URL(req.url ?? '', 'http://localhost');+ const docName = url.searchParams.get('doc');+ if (docName !== null && (docName === '' || !isSafeDocName(docName))) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid doc.', {+ handler: 'lint-config',+ });+ return;+ }+ const base = getLinterBaseConfig?.() ?? DEFAULT_LINTER_CONFIG;+ const configProblems: string[] = [];+ const native = resolveNativeConfigForDoc(contentDir, docName ?? undefined, (problem) =>+ configProblems.push(problem),+ );+ const effective = composeFrontmatterSchemasConfig(+ projectDir ?? contentDir,+ composeEffectiveLinterConfig(base, native),+ (problem) => configProblems.push(problem),+ );+ if (docName === null) configProblems.push(...unmatchedGlobProblems(effective));+ successResponse(+ res,+ 200,+ LintConfigResponseSchema,+ { effective, configFile: native?.file ?? null, configProblems },+ { handler: 'lint-config' },+ );+ } catch (e) {+ errorResponse(+ res,+ 500,+ 'urn:ok:error:internal-server-error',+ 'Failed to resolve lint config.',+ {+ handler: 'lint-config',+ cause: e,+ },+ );+ }+ },+ { handler: 'lint-config', method: 'GET', skipBodyParse: true },+ );++ // Enumerate the project's `.ok/schemas/*.json` files (flat, top-level only)+ // as project-root-relative paths for the mapping picker. A missing dir is+ // an empty list, not an error; bounded so a pathological schemas dir can't+ // produce an unbounded response.+ const handleFrontmatterSchemasList = withValidation(+ EmptyRequestSchema,+ async (_req, res) => {+ try {+ const root = resolve(projectDir ?? contentDir);+ // Two discovery sources: the flat tool-created `.ok/schemas/` scan,+ // plus a filtered content walk for the ecosystem `*.schema.json`+ // convention anywhere in the project. The walk deliberately does NOT+ // re-admit `.ok`: the scan above already covers `.ok/schemas/`, and+ // lifting ContentFilter's always-skip floor here would let this+ // surface enumerate the rest of OK's internal state to find schemas.+ const { schemas, truncated } = listProjectSchemaFiles(root);+ const found = new Set(schemas);+ let walkTruncated = false;+ if (contentFilter !== undefined) {+ const walk = streamShowAllEntries({+ contentDir,+ contentFilter,+ dirFilter: null,+ maxEntries: 20_000,+ });+ let walkResult = await walk.next();+ while (!walkResult.done) {+ const entry = walkResult.value;+ const entryPath = entry.kind === 'asset' ? entry.path : undefined;+ if (entryPath !== undefined && isFrontmatterSchemaAsset(entryPath)) {+ const projectRel = relative(root, resolve(contentDir, entryPath));+ if (!projectRel.startsWith('..') && !isAbsolute(projectRel)) found.add(projectRel);+ }+ walkResult = await walk.next();+ }+ walkTruncated = walkResult.value.truncated;+ }+ const merged = [...found].sort((a, b) => a.localeCompare(b));+ successResponse(+ res,+ 200,+ FrontmatterSchemasListSuccessSchema,+ {+ schemas: merged.slice(0, SCHEMA_LIST_CAP),+ truncated: truncated || walkTruncated || merged.length > SCHEMA_LIST_CAP,+ },+ { handler: 'frontmatter-schemas-list' },+ );+ } catch (e) {+ errorResponse(+ res,+ 500,+ 'urn:ok:error:internal-server-error',+ 'Failed to list frontmatter schemas.',+ { handler: 'frontmatter-schemas-list', cause: e },+ );+ }+ },+ { handler: 'frontmatter-schemas-list', method: 'GET', skipBodyParse: true },+ );++ const handleLintDoc = withValidation(+ EmptyRequestSchema,+ async (req, res) => {+ try {+ const url = new URL(req.url ?? '', 'http://localhost');+ const docName = url.searchParams.get('doc') ?? '';+ if (docName === '' || !isSafeDocName(docName)) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Missing or invalid doc.', {+ handler: 'lint',+ });+ return;+ }+ const docRelPath = resolveDocFilePath(contentDir, docName);+ if (docRelPath === null) {+ errorResponse(res, 404, 'urn:ok:error:doc-not-found', 'Document not found.', {+ handler: 'lint',+ });+ return;+ }+ const baseConfig = getLinterBaseConfig?.() ?? DEFAULT_LINTER_CONFIG;+ const configWarnings: string[] = [];+ const result = await lintDoc({+ projectDir: projectDir ?? contentDir,+ contentDir,+ baseConfig,+ docRelPath,+ onConfigProblem: (problem) => configWarnings.push(problem),+ liveSourceFor: liveLintSourceFor,+ });+ // Absent when there is nothing to report, matching the schema's+ // documented contract and the three sibling lint emitters. `ran` is the+ // field that is always present; do not carry that rule across to this one.+ const lintWarnings = [...configWarnings, ...summarizeLintPluginFailures(result.failures)];+ successResponse(+ res,+ 200,+ LintDocResultSchema,+ { ...result, ...(lintWarnings.length > 0 ? { warnings: lintWarnings } : {}) },+ { handler: 'lint' },+ );+ } catch (e) {+ if (e instanceof SymlinkEscapeError) {+ errorResponse(res, 400, 'urn:ok:error:path-escape', 'Path escape detected.', {+ handler: 'lint',+ });+ return;+ }+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to lint document.', {+ handler: 'lint',+ cause: e,+ });+ }+ },+ { handler: 'lint', method: 'GET', skipBodyParse: true },+ );++ const handleLintAudit = withValidation(+ EmptyRequestSchema,+ async (req, res) => {+ try {+ const url = new URL(req.url ?? '', 'http://localhost');+ const rawTarget = url.searchParams.get('path');+ const target = rawTarget === null || rawTarget === '' ? undefined : rawTarget;+ // Absolute paths and traversal must not reach the walker: an audit+ // response carries offending-text snippets, so an unchecked scope is+ // an arbitrary-directory read for any connected agent.+ if (target !== undefined && !isValidRelativeContentPath(target)) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid path.', {+ handler: 'lint-audit',+ });+ return;+ }+ const baseConfig = getLinterBaseConfig?.() ?? DEFAULT_LINTER_CONFIG;+ const result = await auditProject({+ projectDir: projectDir ?? contentDir,+ contentDir,+ baseConfig,+ targetPath: target,+ liveSourceFor: liveLintSourceFor,+ cache: auditCache,+ auditGeneration: readAuditGeneration,+ });+ successResponse(res, 200, LintAuditResponseSchema, result, { handler: 'lint-audit' });+ } catch (e) {+ if (e instanceof AuditSupersededError) {+ respondAuditSuperseded(res, 'lint-audit');+ return;+ }+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to audit project.', {+ handler: 'lint-audit',+ cause: e,+ });+ }+ },+ { handler: 'lint-audit', method: 'GET', skipBodyParse: true },+ );++ // Unified validation audit: every registered project validator (markdownlint+ // walk + derived-index dead-link read) merged into one source-tagged plane.+ // Additive alongside /api/lint/audit and /api/dead-links, which keep their+ // single-validator contracts.+ const handleAudit = withValidation(+ EmptyRequestSchema,+ async (req, res) => {+ try {+ const url = new URL(req.url ?? '', 'http://localhost');+ const rawTarget = url.searchParams.get('path');+ let target = rawTarget === null || rawTarget === '' ? undefined : rawTarget;+ // Absolute paths and traversal must not reach the validators: the+ // lint walk reads file bytes under this scope, so an unchecked path+ // is an arbitrary-directory read for any connected caller.+ if (target !== undefined && !isValidRelativeContentPath(target)) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid path.', {+ handler: 'audit',+ });+ return;+ }+ // `doc` scopes by docName (extension-less). The client freshness path+ // knows docNames from disk-ack frames, never file extensions, so the+ // extension resolution has to happen here. A doc indexed from a live+ // CRDT session may not be on disk yet — fall back to the default+ // extension so the links validator can still scope to it (mirrors the+ // links validator's own fallback).+ const rawDoc = url.searchParams.get('doc');+ const docParam = rawDoc === null || rawDoc === '' ? undefined : rawDoc;+ if (docParam !== undefined) {+ if (target !== undefined || !isValidRelativeContentPath(docParam)) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid doc.', {+ handler: 'audit',+ });+ return;+ }+ target = resolveDocFilePath(contentDir, docParam) ?? `${docParam}.md`;+ }+ const baseConfig = getLinterBaseConfig?.() ?? DEFAULT_LINTER_CONFIG;+ const validators = createProjectValidators({+ projectDir: projectDir ?? contentDir,+ contentDir,+ baseConfig,+ liveSourceFor: liveLintSourceFor,+ derivedDocumentIndex: derivedDocumentIndex ?? null,+ linksValidation: getLinksValidationSetting?.(),+ admittedDocNames: collectAdmittedDocNames,+ docFilePathFor: (docName) => resolveDocFilePath(contentDir, docName),+ cache: auditCache,+ auditGeneration: readAuditGeneration,+ });+ const result = await runCoalescedAudit(+ validators,+ target,+ AuditCache.fingerprintConfig(baseConfig),+ );+ // `counts=1` tallies the same plane instead of enumerating it — the+ // freshness path behind file-tree tints wants per-file counts, and on a+ // large KB the enumerated bodies are tens of MB it discards on arrival.+ if (url.searchParams.get('counts') === '1') {+ successResponse(+ res,+ 200,+ ValidationAuditCountsResponseSchema,+ toValidationCountsPlane(result),+ { handler: 'audit' },+ );+ return;+ }+ successResponse(res, 200, ValidationAuditResponseSchema, result, { handler: 'audit' });+ } catch (e) {+ if (e instanceof AuditSupersededError) {+ respondAuditSuperseded(res, 'audit');+ return;+ }+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Failed to audit project.', {+ handler: 'audit',+ cause: e,+ });+ }+ },+ { handler: 'audit', method: 'GET', skipBodyParse: true },+ );++ const routes: Record<string, (req: IncomingMessage, res: ServerResponse) => Promise<void>> = {+ '/api/lint/config': handleGetLintConfig,+ '/api/lint/frontmatter-schemas': handleFrontmatterSchemasList,+ '/api/lint': handleLintDoc,+ '/api/lint/audit': handleLintAudit,+ '/api/audit': handleAudit,+ };++ const table: ApiRouteTable = {+ resolve(url) {+ const handler = routes[url];+ if (handler) {+ return { template: url, dispatch: (req, res) => handler(req, res) };+ }+ return null;+ },+ // `isMutating` tracks legacy MUTATING_ROUTES membership, not actual side+ // effects. Every route here is a read and none rode that gate; the+ // write-side lint routes (markdownlint-config / frontmatter-schema / fix)+ // stay in the extension on it.+ isMutating: () => false,+ };++ return {+ paths: Object.keys(routes),+ table,+ };+}diff --git a/packages/server/src/http/skills-read-routes.ts b/packages/server/src/http/skills-read-routes.tsnew file mode 100644index 000000000..39ebe99db--- /dev/null+++ b/packages/server/src/http/skills-read-routes.ts@@ -0,0 +1,324 @@+/**+ * The skills + templates read family — `comment-counts`, `skills/installed`,+ * `templates`, `skill/install-state` — the seventh natively-routed Wave 2+ * group. Same lift shape as the earlier groups: what the handlers closed over+ * in the extension arrives as {@link SkillsReadRouteDeps}, the handler bodies+ * are unchanged, and the extension composes this group's table into its+ * `nativeApi` handle while the legacy dispatch record loses the paths in the+ * same change.+ *+ * `/api/skills` (the skills-list read) deliberately stays in the extension: its+ * handler reads and reassigns the shared mutable skills-catalog generation ++ * cache (`skillsCatalogGen` / `skillsListCache`), which are bumped from ~20+ * legacy sites (the CC1 `files` signal, every mutating skill handler). It moves+ * with the skills mutation family, when that cluster migrates. The installed+ * catalog cache stays there too and is consumed here by reference through+ * `enumerateInstalledSkillsCached`.+ *+ * `skill/install-state` keeps its `checkLocalOpSecurity` pre-body gate — lifted+ * as a dep so the loopback + DNS-rebinding refusal travels with the handler.+ */++import type { IncomingMessage, ServerResponse } from 'node:http';+import { homedir } from 'node:os';+import { resolve } from 'node:path';+import {+ CommentCountsSuccessSchema,+ EmptyRequestSchema,+ isDetectedSkillInProject,+ isSkillOutsideOpenProject,+ SkillInstallStateSuccessSchema,+ SkillsInstalledSuccessSchema,+ TemplatesListSuccessSchema,+} from '@inkeep/open-knowledge-core';+import { resolveProjectIdentity } from '@inkeep/open-knowledge-core/shadow-repo-layout';+import type { enumerateInstalledSkills } from '@inkeep/open-knowledge-core/skills-catalog';+import type { CommentService } from '../comments/comment-service.ts';+import { resolveProjectTemplates } from '../content/templates-resolver.ts';+import { scanGlobalInPlaceSkills, scanInPlaceSkills } from '../in-place-skills.ts';+import { readSkillInstallStateSnapshot } from '../skill-state.ts';+import type { ApiRouteTable } from './api-pipeline.ts';+import { catchErrors } from './catch-errors.ts';+import { errorResponse } from './error-response.ts';+import { withValidation } from './request-validation.ts';+import { successResponse } from './success-response.ts';++export interface SkillsReadRouteDeps {+ contentDir: string;+ projectDir: string | undefined;+ /** Home-dir seam so a rig / embedded host never scans the REAL ~/.claude. */+ homeDirOverride: string | undefined;+ /** `homeDirOverride ?? homedir()` — the resolved skills-home root. */+ skillsHome: string;+ /** The extension's docName safety predicate (path-traversal refusal). */+ isSafeDocName: (docName: string) => boolean;+ /** Only `countThreads` is read (comment-counts); narrowed to it. */+ commentService: Pick<CommentService, 'countThreads'>;+ /**+ * The extension's generation-cached installed-skills enumerator — closes over+ * the shared `installedCatalogCache` / `skillsCatalogGen` that stay in the+ * extension, so it is consumed by reference rather than moved.+ */+ enumerateInstalledSkillsCached: (+ opts: Parameters<typeof enumerateInstalledSkills>[0],+ ) => ReturnType<typeof enumerateInstalledSkills>;+ /** The extension's shared local-op security gate (emits RFC 9457 on refusal). */+ checkLocalOpSecurity: (+ req: IncomingMessage,+ res: ServerResponse,+ opts: { handler: string },+ ) => boolean;+}++export interface SkillsReadRoutes {+ /** 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 createSkillsReadRoutes(deps: SkillsReadRouteDeps): SkillsReadRoutes {+ const {+ contentDir,+ projectDir,+ homeDirOverride,+ skillsHome,+ isSafeDocName,+ commentService,+ enumerateInstalledSkillsCached,+ checkLocalOpSecurity,+ } = deps;++ /**+ * Read-only cross-harness installed-skill enumeration. `GET /api/skills/installed`+ * returns `{ skills, packs }` — every skill OK can see across all harness+ * homes (Claude plugins + the bare skill dirs), normalized + de-duped. Pure+ * read: no home is mutated (NOT in MUTATING_ROUTES). 200 with empty arrays on+ * a machine with nothing installed.+ */+ const handleSkillsInstalled = withValidation(+ EmptyRequestSchema,+ async (_req, res) => {+ try {+ // The catalog is machine-global; the detected sidebar shows it under the+ // OPEN project's scopes. Two moves keep it faithful to the project |+ // global invariant (precedent #50): (1) resolve a linked worktree to its+ // parent-checkout identity so the parent's project-scoped installs+ // (keyed on the parent path) still match here; (2) ALSO scan this+ // project's `.<harness>/skills` dirs so every harness's project skills+ // surface, not just Claude plugins. The SAME identity is used to scan,+ // stamp, and filter — drop skills bound to a *different* project.+ const identity = resolveProjectIdentity(projectDir ?? contentDir);+ // Same `homeDirOverride` seam as every other home-scanning surface here —+ // without it a rig (or embedded host) enumerates the REAL ~/.claude/plugins.+ const catalog = enumerateInstalledSkillsCached({+ projectDir: identity,+ ...(homeDirOverride !== undefined ? { home: homeDirOverride } : {}),+ });+ // In-place editor-dir skills are first-class `/api/skills`+ // entries at BOTH scopes — dropping them here keeps the same skill from+ // double-listing as a "detected" row. What remains detected: plugin-cache+ // skills (`~/.claude/plugins/**`), which the in-place scans don't cover.+ const inPlaceNames = new Set(scanInPlaceSkills(contentDir).map((s) => s.name));+ const globalInPlaceNames = new Set(scanGlobalInPlaceSkills(skillsHome).map((s) => s.name));+ const result = {+ ...catalog,+ skills: catalog.skills+ .filter(+ (s) =>+ isDetectedSkillInProject(s.provenance, identity) &&+ !(s.provenance.scope === 'project'+ ? inPlaceNames.has(s.name)+ : globalInPlaceNames.has(s.name)),+ )+ // `identity` is the PARENT checkout for a linked worktree, so a skill+ // can match the project while living in a tree the user does not have+ // open. Stamp that so the client can refuse an in-place edit that would+ // land in another checkout on another branch.+ //+ // The reference is the OPEN PROJECT ROOT — `projectDir ?? contentDir`,+ // the same expression `identity` is derived from but WITHOUT the+ // worktree→parent resolution. Not `identity` (that resolution makes the+ // test vacuously false), and not `contentDir`: under `content.dir: docs`+ // contentDir is `<projectDir>/docs` while harness skill dirs sit at+ // `<projectDir>/.codex/skills/…`, so every project skill in the user's+ // OWN checkout would be flagged foreign.+ .map((s) =>+ isSkillOutsideOpenProject(s.provenance, s.home, projectDir ?? contentDir)+ ? { ...s, outsideProject: true }+ : s,+ ),+ };+ successResponse(res, 200, SkillsInstalledSuccessSchema, result, {+ handler: 'skills-installed',+ });+ } catch (e) {+ errorResponse(+ res,+ 500,+ 'urn:ok:error:internal-server-error',+ 'Failed to enumerate installed skills.',+ { handler: 'skills-installed', cause: e },+ );+ }+ },+ { handler: 'skills-installed', 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+ * `{ counts: { a: 2, b: 0 } }`; `?prefix=folder` returns the same shape for+ * every doc under that folder that carries threads (sparse — a comment-free+ * subtree yields `{}`), which is how an `ls` entry gets a folder rollup+ * without a request per file.+ *+ * Read-only, so it stays out of `MUTATING_ROUTES` — unlike `/api/comments`,+ * whose POST creates threads. docNames failing `isSafeDocName` are silently+ * dropped, matching backlink-counts; a malformed `prefix` is a 400 because+ * dropping it would silently widen the query to the whole project.+ */+ const handleCommentCounts = withValidation(+ EmptyRequestSchema,+ async (req, res) => {+ try {+ const url = new URL(req.url ?? '', 'http://localhost');+ const prefix = url.searchParams.get('prefix');+ const raw = url.searchParams.get('docNames');+ if (prefix === null && raw === null) {+ errorResponse(+ res,+ 400,+ 'urn:ok:error:invalid-request',+ 'Missing docNames or prefix parameter.',+ { handler: 'comment-counts' },+ );+ return;+ }+ let counts: Record<string, number> = {};+ if (prefix !== null) {+ const trimmed = prefix.trim();+ if (trimmed !== '' && !isSafeDocName(trimmed)) {+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid prefix parameter.', {+ handler: 'comment-counts',+ });+ return;+ }+ counts = Object.fromEntries(await commentService.countThreads({ prefix: trimmed }));+ } else {+ const docNames = (raw ?? '')+ .split(',')+ .map((name) => name.trim())+ .filter((name) => name !== '' && isSafeDocName(name));+ counts = Object.fromEntries(await commentService.countThreads({ docNames }));+ }+ successResponse(+ res,+ 200,+ CommentCountsSuccessSchema,+ { counts },+ {+ handler: 'comment-counts',+ },+ );+ } catch (e) {+ errorResponse(+ res,+ 500,+ 'urn:ok:error:internal-server-error',+ 'Failed to read comment counts.',+ { handler: 'comment-counts', cause: e },+ );+ }+ },+ { handler: 'comment-counts', method: 'GET', skipBodyParse: true },+ );++ /**+ * Project-wide flat enumeration of every `<folder>/.ok/templates/*.md`.+ * The single-template `/api/template` endpoint is per-folder + walks+ * leaf → root for closest-wins resolution; this surface is the editor's+ * empty-state list (every template the user can pick from, with the+ * `source_folder` that owns each one). Skips the same dirs as the+ * directory-scan walker — see `resolveProjectTemplates`.+ */+ const handleTemplatesList = withValidation(+ EmptyRequestSchema,+ catchErrors(+ async (_req, res) => {+ const resolvedContentDir = resolve(contentDir);+ const result = await resolveProjectTemplates(resolvedContentDir);+ // Drop `scope` from each entry — every flat-enumeration entry is+ // implicitly `scope: 'local'` to its own `source_folder`, so the+ // field carries no information here. `TemplatesListEntrySchema` is+ // `.strict()` and would otherwise reject the response.+ const templates = result.templates.map((t) => {+ const { scope: _scope, ...rest } = t;+ return rest;+ });+ successResponse(+ res,+ 200,+ TemplatesListSuccessSchema,+ { templates, truncated: result.truncated },+ { handler: 'templates-list' },+ );+ },+ { handler: 'templates-list', title: 'Failed to list templates.' },+ ),+ { handler: 'templates-list', method: 'GET', skipBodyParse: true },+ );++ const handleSkillInstallState = withValidation(+ EmptyRequestSchema,+ catchErrors(+ async (_req, res) => {+ const snapshot = await readSkillInstallStateSnapshot(homedir());+ successResponse(+ res,+ 200,+ SkillInstallStateSuccessSchema,+ { ...snapshot },+ {+ handler: 'skill-install-state',+ extraHeaders: { 'Cache-Control': 'no-store' },+ },+ );+ },+ { handler: 'skill-install-state', title: 'Failed to read skill install state.' },+ ),+ {+ handler: 'skill-install-state',+ method: 'GET',+ skipBodyParse: true,+ preBodyGate: (req, res) => checkLocalOpSecurity(req, res, { handler: 'skill-install-state' }),+ },+ );++ const routes: Record<string, (req: IncomingMessage, res: ServerResponse) => Promise<void>> = {+ '/api/comment-counts': handleCommentCounts,+ '/api/skills/installed': handleSkillsInstalled,+ '/api/templates': handleTemplatesList,+ '/api/skill/install-state': handleSkillInstallState,+ };++ const table: ApiRouteTable = {+ resolve(url) {+ const handler = routes[url];+ if (handler) {+ return { template: url, dispatch: (req, res) => handler(req, res) };+ }+ return null;+ },+ // `isMutating` tracks legacy MUTATING_ROUTES membership, not actual side+ // effects. Every route here is a read and none rode that gate.+ // `skill/install-state` enforces its loopback + DNS-rebinding refusal via+ // the `checkLocalOpSecurity` pre-body gate, not the mutating gate.+ isMutating: () => false,+ };++ return {+ paths: Object.keys(routes),+ table,+ };+}