Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(ok): Wave 2 group 8 comments/sync/share/git native (PRD-8401) (#3987)

omar-inkeep55fc5f2cc741
diff --git a/packages/app/tests/meta/showok-caller-coverage.test.ts b/packages/app/tests/meta/showok-caller-coverage.test.ts
index 661fda153..82dfd86f4 100644
--- a/packages/app/tests/meta/showok-caller-coverage.test.ts
+++ b/packages/app/tests/meta/showok-caller-coverage.test.ts
@@ -32,6 +32,11 @@ const API_EXT_PATH = join(SERVER_SRC_ROOT, 'api-extension.ts');
// Wave 2 lift; the deps interface restates the walk-opts contract's showOk
// field types.
const DOCUMENT_ROUTES_PATH = join(SERVER_SRC_ROOT, 'http/document-routes.ts');
+// Hosts `toOpenTarget` (the sync popover's open-target resolver, the second
+// authorized consumer) after its Wave 2 lift out of api-extension.ts with the
+// git family — moved whole with its sole consumer, the worktree-status
+// handler; the authorization rationale travels with the region check below.
+const GIT_ROUTES_PATH = join(SERVER_SRC_ROOT, 'http/git-routes.ts');
/** Recursively enumerate `.ts` files under `dir`, skipping test files. */
function listProductionTsFiles(dir: string): string[] {
@@ -66,7 +71,12 @@ function sliceRegion(source: string, startAnchor: string, endAnchor: RegExp): [n
describe('showOk caller coverage', () => {
test('no server/cli production file outside the sanctioned files names showOk', () => {
- const allowedFiles = new Set([CONTENT_FILTER_PATH, API_EXT_PATH, DOCUMENT_ROUTES_PATH]);
+ const allowedFiles = new Set([
+ CONTENT_FILTER_PATH,
+ API_EXT_PATH,
+ DOCUMENT_ROUTES_PATH,
+ GIT_ROUTES_PATH,
+ ]);
const offenders: string[] = [];
for (const root of [SERVER_SRC_ROOT, CLI_SRC_ROOT]) {
for (const file of listProductionTsFiles(root)) {
@@ -86,7 +96,22 @@ describe('showOk caller coverage', () => {
'export interface StreamShowAllOpts',
/export async function walkContentDirForShowAll/,
);
- // Region A2: `toOpenTarget`, the sync popover's open-target resolver.
+ const outside: string[] = [];
+ for (const match of source.matchAll(/\bshowOk\b/g)) {
+ const offset = match.index ?? 0;
+ const inWalk = offset >= walkStart && offset < walkEnd;
+ if (!inWalk) {
+ const line = source.slice(0, offset).split('\n').length;
+ outside.push(
+ `api-extension.ts:${line} — showOk outside the walk-opts region. ` +
+ 'Only the tree-listing path may pass the flag; a new consumer needs a deliberate ' +
+ 'spec decision, not a new call site.',
+ );
+ }
+ }
+
+ // git-routes.ts (post-lift home of `toOpenTarget`, the sync popover's
+ // open-target resolver — Region A2 before the git family's Wave 2 lift).
//
// A second AUTHORIZED consumer, not a leak. It enumerates nothing — the
// rows come from `git status`, which never consults ContentFilter — and
@@ -98,20 +123,19 @@ describe('showOk caller coverage', () => {
// unconditionally (OK_ALWAYS_SKIP_CHILDREN), so per-machine state cannot
// reach the wire through this path either way.
// Starts at the docblock, which states the contract and names the flag.
+ const gitSource = readFileSync(GIT_ROUTES_PATH, 'utf8');
const [openTargetStart, openTargetEnd] = sliceRegion(
- source,
+ gitSource,
' * Where a project-relative working-tree path opens',
/\n {2}\/\*\*/,
);
- const outside: string[] = [];
- for (const match of source.matchAll(/\bshowOk\b/g)) {
+ for (const match of gitSource.matchAll(/\bshowOk\b/g)) {
const offset = match.index ?? 0;
- const inWalk = offset >= walkStart && offset < walkEnd;
const inOpenTarget = offset >= openTargetStart && offset < openTargetEnd;
- if (!inWalk && !inOpenTarget) {
- const line = source.slice(0, offset).split('\n').length;
+ if (!inOpenTarget) {
+ const line = gitSource.slice(0, offset).split('\n').length;
outside.push(
- `api-extension.ts:${line} — showOk outside the walk-opts region. ` +
+ `http/git-routes.ts:${line} — showOk outside the toOpenTarget region. ` +
'Only the tree-listing path may pass the flag; a new consumer needs a deliberate ' +
'spec decision, not a new call site.',
);
@@ -154,5 +178,6 @@ describe('showOk caller coverage', () => {
// regions above to be revisited rather than rotting into dead authority.
expect(readFileSync(CONTENT_FILTER_PATH, 'utf8')).toContain('showOk?: boolean');
expect(readFileSync(DOCUMENT_ROUTES_PATH, 'utf8')).toContain("searchParams.get('showOk')");
+ expect(readFileSync(GIT_ROUTES_PATH, 'utf8')).toContain('showOk: true');
});
});
diff --git a/packages/server/src/api-comments-composition.test.ts b/packages/server/src/api-comments-composition.test.ts
new file mode 100644
index 000000000..b7bb4ea16
--- /dev/null
+++ b/packages/server/src/api-comments-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, parseProblem, rawRequest } from './composition-rig.test-helper.ts';
+
+/**
+ * Characterization: the natively-routed comments group over a REAL socket
+ * through the composed `bootServer` stack — native registration and the
+ * shared admission posture. Gate BEHAVIOR is owned by
+ * `api-admission-composition.test.ts` (path-agnostic by construction); the
+ * rebound-Host pin below re-pins gate REACHABILITY for this family — a
+ * native-registration bug could mount the group outside
+ * `createApiRequestPipeline` without changing any happy-path response, and a
+ * hostile-header probe is the only wire signal that tells those apart. The
+ * wire cannot distinguish the mutating gate from the read gate (both apply
+ * the same loopback + workspace-Host checks), so the mutating DECLARATION
+ * itself is pinned at the table tier in `http/comment-routes.test.ts`.
+ */
+
+let tmpRoot: string;
+let server: BootedServer;
+
+beforeAll(async () => {
+ tmpRoot = await mkdtemp(resolve(tmpdir(), 'ok-comments-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('comments group over the composed listener — served natively', () => {
+ test('both routes are registered natively (PUT → 405 with the verb map, not a route-miss 404)', async () => {
+ const comments = await fetch(`http://127.0.0.1:${server.port}/api/comments`, { method: 'PUT' });
+ expect(comments.status).toBe(405);
+ expect(comments.headers.get('allow')).toBe('GET, POST');
+ const comment = await fetch(`http://127.0.0.1:${server.port}/api/comment`, { method: 'PUT' });
+ expect(comment.status).toBe(405);
+ expect(comment.headers.get('allow')).toBe('GET, POST, DELETE');
+ });
+
+ test('list reaches the real handler (project-wide 200 on an empty store)', async () => {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/comments`);
+ expect(res.status).toBe(200);
+ expect(await res.json()).toEqual({ threads: [] });
+ });
+
+ test('missing-id read reaches the real handler (its own 400)', async () => {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/comment`);
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:invalid-request');
+ expect(res.headers.get('x-request-id')).not.toBeNull();
+ });
+
+ test('a rebound Host is refused on every verb — the URL-keyed mutating gate covers the GET arms', async () => {
+ for (const path of ['/api/comments', '/api/comment']) {
+ const res = await rawRequest(server.port, path, {
+ headers: { Host: 'evil.example' },
+ });
+ expect(res.status, path).toBe(403);
+ expect(parseProblem(res.body).type, path).toBe('urn:ok:error:host-not-allowed');
+ }
+ });
+
+ test('chained groups still 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 comment = await fetch(`http://127.0.0.1:${server.port}/api/comment`);
+ expect(comment.status).toBe(400);
+ });
+});
diff --git a/packages/server/src/api-extension.branch-info.test.ts b/packages/server/src/api-extension.branch-info.test.ts
index 2861dd106..fff0fb3b3 100644
--- a/packages/server/src/api-extension.branch-info.test.ts
+++ b/packages/server/src/api-extension.branch-info.test.ts
@@ -47,7 +47,7 @@ async function bootRig(
const { Hocuspocus } = await import('@hocuspocus/server');
const { AgentSessionManager } = await import('./agent-sessions.ts');
- const { createApiExtension } = await import('./api-extension.ts');
+ const { createApiExtension } = await import('./api-extension.test-helper.ts');
const hocuspocus = new Hocuspocus({ quiet: true });
const sessionManager = new AgentSessionManager(hocuspocus);
diff --git a/packages/server/src/api-extension.checkout.test.ts b/packages/server/src/api-extension.checkout.test.ts
index 723d95559..d2c200226 100644
--- a/packages/server/src/api-extension.checkout.test.ts
+++ b/packages/server/src/api-extension.checkout.test.ts
@@ -51,7 +51,7 @@ async function bootRig(
const { Hocuspocus } = await import('@hocuspocus/server');
const { AgentSessionManager } = await import('./agent-sessions.ts');
- const { createApiExtension } = await import('./api-extension.ts');
+ const { createApiExtension } = await import('./api-extension.test-helper.ts');
const hocuspocus = new Hocuspocus({ quiet: true });
const sessionManager = new AgentSessionManager(hocuspocus);
diff --git a/packages/server/src/api-extension.ts b/packages/server/src/api-extension.ts
index 214850d81..7a2edfdf6 100644
--- a/packages/server/src/api-extension.ts
+++ b/packages/server/src/api-extension.ts
@@ -47,9 +47,6 @@ import {
AgentWriteSuccessSchema,
applyPatchToFm,
type BatchEntryError,
- BranchInfoResponseSchema,
- CheckoutRequestSchema,
- CheckoutResponseSchema,
CONFIG_DOC_NAME_OKIGNORE,
type ConfigDiagnosticsReport,
changedBlockRange,
@@ -66,19 +63,15 @@ import {
EDITOR_PROJECT_SKILL_ROOT,
type EditorId,
EmptyRequestSchema,
- encodeShareUrl,
estimateSkillCost,
externalSkillLiveDocName,
FrontmatterPatchRequestSchema,
FrontmatterPatchSuccessSchema,
FrontmatterSchemaWriteRequestSchema,
- type GitWorktreeOpenTarget,
- GitWorktreeStatusSuccessSchema,
type HeadingEntry,
type InlineAssetMediaKind,
InstallSkillRequestSchema,
InstallSkillSuccessSchema,
- InvalidShareUrlError,
isManagedArtifactDocName,
isOpenKnowledgeSkillsSource,
isSkillInstallTarget,
@@ -116,7 +109,6 @@ import {
PROJECT_SKILL_EDITOR_IDS,
type Principal,
type ProblemType,
- parseCanonicalGitHubShareUrl,
parseFrontmatterRecord,
prependFrontmatter,
projectSkillContentDocName,
@@ -126,14 +118,6 @@ import {
readFmMap,
SaveVersionRequestSchema,
SaveVersionSuccessSchema,
- ShareConstructUrlRequestSchema,
- ShareConstructUrlResponseSchema,
- SharePublishNameCheckResponseSchema,
- SharePublishOwnersResponseSchema,
- SharePublishRequestSchema,
- SharePublishResponseSchema,
- ShareTargetStatusRequestSchema,
- ShareTargetStatusResponseSchema,
SKILL_NAME_REGEX,
SkillDeleteSuccessSchema,
SkillDuplicateRequestSchema,
@@ -177,15 +161,6 @@ import {
SkillUninstallRequestSchema,
SkillUninstallSuccessSchema,
SYSTEM_DOC_NAME,
- SyncConflictContentSuccessSchema,
- SyncConflictsSuccessSchema,
- SyncResolveBlockingRequestSchema,
- SyncResolveBlockingSuccessSchema,
- SyncResolveConflictRequestSchema,
- SyncResolveConflictSuccessSchema,
- SyncStatusSchema,
- SyncTriggerRequestSchema,
- SyncTriggerSuccessSchema,
scanHeadingLine,
skillLiveDocName,
stripFrontmatter,
@@ -256,7 +231,6 @@ import {
type SummaryResponse,
} from './agent-write-summary.ts';
import { resolveBundledSkillDir } from './build-skill-zip.ts';
-import { createCommentApi } from './comments/comment-api.ts';
import { CommentIndex } from './comments/comment-index.ts';
import { CommentService } from './comments/comment-service.ts';
import { CommentThreadStore } from './comments/thread-store.ts';
@@ -334,42 +308,8 @@ import {
parseFrontmatterMetadata,
} from './page-identity.ts';
import type { RecentlyRemovedDocs } from './recently-removed-docs.ts';
-import {
- buildGitHubBlobUrl,
- buildGitHubTreeUrl,
- emitShareConstructUrlLog,
- isValidSharePath,
- SHARE_BASE_URL,
- SHARE_CONSTRUCT_URL_HANDLER_TAG,
-} from './share/construct-url.ts';
-import { computeShareFreshness } from './share/freshness.ts';
-import {
- branchExistsOnOrigin,
- originGitHubHost,
- readGitHeadBranch,
- readOriginGitHubRepo,
-} from './share/git-context.ts';
-import {
- emitSharePublishLog,
- isValidShareOwnerName,
- isValidShareRepoName,
- parseNameCheckEvent,
- parseOwnersEvent,
- parsePublishEvent,
- pickTerminalJsonLine,
- redactShareSubprocessStderr,
- SHARE_PUBLISH_HANDLER_TAG,
- SHARE_PUBLISH_KEY,
- SHARE_PUBLISH_NAME_CHECK_HANDLER_TAG,
- SHARE_PUBLISH_NAME_CHECK_KEY,
- SHARE_PUBLISH_OWNERS_HANDLER_TAG,
- SHARE_PUBLISH_OWNERS_KEY,
- SHARE_PUBLISH_TIMEOUT_MS,
-} from './share/publish.ts';
-import {
- computeShareTargetStatus,
- SHARE_TARGET_STATUS_HANDLER_TAG,
-} from './share/target-status.ts';
+import { originGitHubHost } from './share/git-context.ts';
+import { redactShareSubprocessStderr } from './share/publish.ts';
import {
BUNDLE_IDS,
BUNDLE_SCOPE,
@@ -394,7 +334,6 @@ import {
validateSkillForInstall,
} from './skill-projection.ts';
import { rewriteSkillRefsAcrossScope, type SkillRefRewrite } from './skill-ref-rename.ts';
-import { assertRealpathWithinDir } from './symlink-guard.ts';
/** Does the bundle at `dir` carry a `metadata.pack` marker in its frontmatter? */
function bundleSelfIdentifiesAsPack(dir: string): boolean {
@@ -429,14 +368,15 @@ import {
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';
-import { withHiddenWindowsConsole } from './child-process-windows-hide.ts';
-import type { ResolveStrategy } from './conflict-storage.ts';
+import {
+ LOCAL_OP_PIPE_STDIO_OPTIONS,
+ withHiddenWindowsConsole,
+} from './child-process-windows-hide.ts';
import {
isReservedProjectStatePath,
listManagedDocNamesUnderFolder,
} from './content/managed-doc-enum.ts';
import type { ContentFilter } from './content-filter.ts';
-import { isShareableOkArtifact } from './content-filter.ts';
import { safeContentPath } from './content-path.ts';
import {
type DerivedDocumentIndexApiPort,
@@ -480,18 +420,11 @@ import {
tracedRmSync,
tracedWriteFileSync,
} from './fs-traced.ts';
-import {
- BRANCH_INFO_HANDLER_TAG,
- computeBranchInfo,
- isValidBranchInfoPath,
- isValidBranchName,
-} from './git-branch-info.ts';
-import { CHECKOUT_HANDLER_TAG, runCheckoutFlow } from './git-checkout.ts';
-import { buildSyncCredentialConfig, withParentLock } from './git-handle.ts';
+import { withParentLock } from './git-handle.ts';
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 { createCommentRoutes } from './http/comment-routes.ts';
import { createConfigSystemRoutes } from './http/config-system-routes.ts';
import { createDocumentRoutes } from './http/document-routes.ts';
import {
@@ -506,6 +439,7 @@ import {
type RenamedDocMapping,
} from './http/file-ops-routes.ts';
import { createFolderTemplateRoutes } from './http/folder-template-routes.ts';
+import { createGitRoutes } from './http/git-routes.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';
@@ -516,9 +450,11 @@ import { createMetricsRoutes } from './http/metrics-routes.ts';
import { getRequestId } from './http/request-id.ts';
import { withValidation } from './http/request-validation.ts';
import { createSeedRoutes } from './http/seed-routes.ts';
+import { createShareRoutes } from './http/share-routes.ts';
import { createSkillsReadRoutes } from './http/skills-read-routes.ts';
import { createSkillsShRoutes } from './http/skills-sh-routes.ts';
import { successResponse } from './http/success-response.ts';
+import { createSyncRoutes } from './http/sync-routes.ts';
import { createSystemActionsRoutes } from './http/system-actions-routes.ts';
import {
createWorkspaceToolsRoutes,
@@ -609,7 +545,6 @@ import {
shadowGit,
type WriterIdentity,
} from './shadow-repo.ts';
-import { shouldResetAmbientCredentials } from './share/git-context.ts';
import { isDisallowedGitSpec, rejectDisallowedGitSpec } from './skill-git-spec-guard.ts';
import { resolveSkillInstallReportSettings } from './skill-install-report-config.ts';
import {
@@ -808,22 +743,6 @@ export const MANAGED_RENAME_ORIGIN = {
const log = getLogger('api');
-/**
- * Detects git merge-conflict marker triples at start-of-line. Requires
- * ALL THREE sentinels (`<<<<<<< `, `=======`, `>>>>>>> `) to co-occur —
- * git always writes the trio together, so single-sentinel matching would
- * false-positive on legitimate user content (e.g., a CommonMark setext H1
- * underline of exactly 7 `=` characters: `My Title\n=======`).
- *
- * Used by the `?source=ytext` branch of the conflict-content handler to
- * decide whether the live Y.Text snapshot is usable as `ours` (no marker
- * triple → safe to surface live edits) or polluted by the file watcher's
- * reopen-time disk seed (triple present → fall back to git-index `ours`).
- */
-function ytextHasConflictMarkers(text: string): boolean {
- return /^<{7} /m.test(text) && /^={7}$/m.test(text) && /^>{7} /m.test(text);
-}
-
/** Validates a docName and builds a shadow-repo-safe path.
* Uses the same traversal check as safeContentPath (reject `..` and null bytes)
* but allows `/` for nested content directories (e.g. `test-content/test-doc`). */
@@ -2286,7 +2205,8 @@ export interface ApiExtensionOptions {
* Closure-captured snapshot of `Y.Text('source').toString()` for a loaded
* doc, returning `null` when the doc is not currently loaded server-side.
* Threaded from `server-factory.ts` (where it lives alongside the bridge
- * + persistence wiring) so `handleSyncConflictContent` can serve the
+ * + persistence wiring) so `handleSyncConflictContent` (now in
+ * `http/sync-routes.ts`) can serve the
* `?source=ytext` override with the canonical
* `prependFrontmatter(stripFrontmatter(ytext))` recompose. Optional —
* when omitted, the `?source=ytext` branch falls back to `git show :2:`
@@ -7767,9 +7687,6 @@ export function createApiExtension(
const LOCAL_OP_STDERR_ONLY_OPTIONS: { stdio: ['ignore', 'ignore', 'pipe'] } = {
stdio: ['ignore', 'ignore', 'pipe'],
};
- const LOCAL_OP_PIPE_STDIO_OPTIONS: { stdio: ['ignore', 'pipe', 'pipe'] } = {
- stdio: ['ignore', 'pipe', 'pipe'],
- };
const LOCAL_OP_IGNORED_STDIO_OPTIONS: Pick<SpawnOptions, 'stdio'> = {
stdio: 'ignore',
};
@@ -8308,6 +8225,17 @@ export function createApiExtension(
const LOCAL_OP_AUTH_PAT_KEY = '/api/local-op/auth/pat';
const LOCAL_OP_AUTH_GH_LOGIN_KEY = '/api/local-op/auth/gh-login';
+ /**
+ * Wall-clock bound for the short, non-interactive auth CLI probes
+ * (`auth status`, `auth signout`). Deliberately NOT `LOCAL_OP_TIMEOUT_MS`
+ * (10 min, sized for clone) — these spawn no device flow and normally
+ * return in milliseconds; the bound only exists to cut loose a wedged
+ * keychain read or a stalled GitHub API call (`auth status` round-trips to
+ * GitHub via octokit with no client timeout of its own; gh detection
+ * carries its own 5s bound).
+ */
+ const LOCAL_OP_AUTH_SUBPROCESS_TIMEOUT_MS = 30_000;
+
/**
* Keepalive cadence for the two streaming auth flows. Between `verification`
* and `complete` the device flow writes nothing for as long as the user takes
@@ -8718,28 +8646,49 @@ export function createApiExtension(
env: { ...process.env },
}),
);
- let timedOut = false;
+ // Settle AT the timer, not at 'close' — the package-wide timeout-kill
+ // shape (illustrative precedents: `rename-log.ts`, `acp/archive.ts`,
+ // `acp/login-shell-path.ts`; mirrored by `spawnShareSubprocess` in
+ // `http/share-routes.ts`, whose docblock asserts this mirror).
+ // Settlement must not depend on the child cooperating ('close' waits
+ // on shared stdio; SIGKILL cannot reap uninterruptible sleep), and
+ // the timeout must reject rather than resolve partial stdout: the
+ // downstream JSON parse would fall back to `{ authenticated: false }`,
+ // a wrong-result "not logged in" UX for an authenticated user.
+ // Surfaces as 500 `auth-failed` via the outer catch + Pino log, and
+ // frees the localOpGuard slot in the outer `finally`.
+ let settled = false;
const killTimer = setTimeout(() => {
- timedOut = true;
- child.kill('SIGTERM');
- }, 30_000);
+ if (settled) return;
+ settled = true;
+ try {
+ child.kill('SIGKILL');
+ } catch {
+ // child may already be dead
+ }
+ // Tear the pipes down at settle: a D-state child (or a grandchild
+ // holding the write-ends) can keep streaming into our buffers
+ // after the response has already 500'd — destroy bounds that.
+ child.stdout.destroy();
+ child.stderr.destroy();
+ reject(
+ new Error(
+ `auth status subprocess timed out after ${LOCAL_OP_AUTH_SUBPROCESS_TIMEOUT_MS}ms`,
+ ),
+ );
+ }, LOCAL_OP_AUTH_SUBPROCESS_TIMEOUT_MS);
+ killTimer.unref?.();
const chunks: Buffer[] = [];
child.stdout.on('data', (chunk: Buffer) => chunks.push(chunk));
child.on('close', () => {
+ if (settled) return;
+ settled = true;
clearTimeout(killTimer);
- // Reject on timeout — without this, a hung subprocess (slow
- // keychain probe, network stall) would resolve with whatever
- // (empty / partial) stdout was buffered. The downstream JSON
- // parse falls back to `{ authenticated: false }`, producing a
- // wrong-result "not logged in" UX for an authenticated user.
- // Surfaces as 500 `auth-failed` via the outer catch + Pino log.
- if (timedOut) {
- reject(new Error('auth status subprocess timed out after 30s'));
- return;
- }
resolve(Buffer.concat(chunks).toString('utf-8'));
});
child.on('error', (err) => {
+ if (settled) return;
+ settled = true;
clearTimeout(killTimer);
reject(err);
});
@@ -8936,9 +8885,35 @@ export function createApiExtension(
}),
);
+ // The timer is a SETTLE branch (same latch discipline as the auth-status
+ // spawn): a child wedged past any signal must not leave the stream open
+ // and the guard slot held until the client happens to disconnect. SIGKILL
+ // is fire-and-forget hygiene; the stdio teardown bounds buffering from a
+ // D-state child or a grandchild holding the pipe write-ends. Repos keeps
+ // the 10-minute LOCAL_OP_TIMEOUT_MS its siblings dropped to 30s: `auth
+ // repos` paginates every repository visible to the token under GitHub
+ // rate limits, which legitimately runs minutes on large accounts.
const killTimer = setTimeout(() => {
- child.kill('SIGTERM');
+ if (settled) return;
+ settled = true;
+ try {
+ child.kill('SIGKILL');
+ } catch {
+ // child may already be dead
+ }
+ child.stdout.destroy();
+ child.stderr.destroy();
+ if (!res.writableEnded) {
+ writeStreamError(
+ 500,
+ 'urn:ok:error:auth-failed',
+ `Auth repos subprocess timed out after ${LOCAL_OP_TIMEOUT_MS}ms.`,
+ );
+ }
+ res.end();
+ localOpGuard.release(LOCAL_OP_AUTH_REPOS_KEY);
}, LOCAL_OP_TIMEOUT_MS);
+ killTimer.unref?.();
child.stdout.on('data', (chunk: Buffer) => {
stdoutBuffer += chunk.toString('utf-8');
@@ -8979,8 +8954,8 @@ export function createApiExtension(
});
// `localOpGuard.release()` lives INSIDE the `settled` guard at every
- // exit branch (child close, child error, client disconnect) so the
- // concurrency guard is released at most once. Releasing outside the
+ // exit branch (timeout, child close, child error, client disconnect) so
+ // the concurrency guard is released at most once. Releasing outside the
// guard would double-release when one branch fires after another —
// most reliably reproduced by client disconnect mid-subprocess, where
// res.on('close') fires first, then the killed child triggers
@@ -9073,14 +9048,38 @@ export function createApiExtension(
env: { ...process.env },
}),
);
+ // Settle AT the timer — same latch as the auth-status spawn above.
+ // The previous shape (SIGTERM-only timer, settle only on 'close')
+ // carried two defects: a wedged child never emits 'close', so the
+ // promise never settles and the `finally` never releases the guard
+ // slot (permanent 429); and with no timed-out flag, a child that
+ // DID close after the SIGTERM resolved as success. No stdio
+ // teardown needed — this spawn ignores all three streams.
+ let settled = false;
const killTimer = setTimeout(() => {
- child.kill('SIGTERM');
- }, 30_000);
+ if (settled) return;
+ settled = true;
+ try {
+ child.kill('SIGKILL');
+ } catch {
+ // child may already be dead
+ }
+ reject(
+ new Error(
+ `auth signout subprocess timed out after ${LOCAL_OP_AUTH_SUBPROCESS_TIMEOUT_MS}ms`,
+ ),
+ );
+ }, LOCAL_OP_AUTH_SUBPROCESS_TIMEOUT_MS);
+ killTimer.unref?.();
child.on('close', () => {
+ if (settled) return;
+ settled = true;
clearTimeout(killTimer);
resolve();
});
child.on('error', (err) => {
+ if (settled) return;
+ settled = true;
clearTimeout(killTimer);
reject(err);
});
@@ -9186,770 +9185,93 @@ export function createApiExtension(
},
);
- // ─── Security helpers for sync endpoints ────────────────────────────────────
- // Sync endpoints reuse the shared loopback + origin check from local-op-security.ts
- // to avoid duplicating the same logic (checkLocalOpSecurity already imported above).
-
- // ─── Sync endpoints ──────────────────────────────────────────────────────────
-
- async function handleSyncStatus(req: IncomingMessage, res: ServerResponse): Promise<void> {
- if (!checkLocalOpSecurity(req, res, { handler: 'sync-status' })) return;
- if (req.method !== 'GET') {
- errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {
- handler: 'sync-status',
- extraHeaders: { Allow: 'GET' },
- });
- return;
- }
- try {
- const engine = getSyncEngine?.();
- if (!engine) {
- // Shape must stay aligned with SyncStatus (see sync-engine.ts) — the UI
- // reads these fields unconditionally. Dormant fallback when the engine
- // isn't constructed (no remote, sync disabled at boot).
- successResponse(
- res,
- 200,
- SyncStatusSchema,
- {
- state: 'dormant',
- lastSyncUtc: null,
- lastFetchUtc: null,
- lastPushedSha: null,
- ahead: 0,
- behind: 0,
- consecutiveFailures: 0,
- conflictCount: 0,
- hasRemote: false,
- syncEnabled: false,
- identityUnresolved: false,
- remote: null,
- },
- { handler: 'sync-status' },
- );
- return;
- }
- // Lazy remote re-detection: if the user ran `git remote add origin <url>`
- // after the server booted, refresh `hasRemote` so the Settings → Sync
- // empty state and badge update without an app restart. No-op once a
- // remote has been observed.
- await engine.refreshRemote();
- successResponse(res, 200, SyncStatusSchema, engine.getStatus(), {
- handler: 'sync-status',
- });
- } catch (e) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: 'sync-status',
- cause: e,
- });
- }
- }
-
/**
- * Where a project-relative working-tree path opens, or undefined when it
- * opens nowhere. Resolves to the same two routes the Files sidebar uses, so
- * a row in the sync popover behaves like the same file in the tree.
+ * `POST /api/install-skill` — build `openknowledge.skill` and open it via
+ * the OS file association so Claude Desktop's native install dialog takes
+ * over. Web-host counterpart of the Electron `okDesktop.skill.buildAndOpen`
+ * bridge — both delegate to `buildAndOpenSkill` in `skill-install.ts`.
*
- * Order is the whole design. File-index membership decides `doc` — the index
- * holds exactly what the editor owns, so a gitignored `.md` falls through to
- * the asset viewer rather than opening an editable surface it is not indexed
- * for. Everything else that survives the filter's FLOORS is an `asset`: the
- * text-view endpoint has no extension gate, so `.gitignore`, `opencode.json`
- * and `.ok/config.yml` all render, and the viewer's own fallback pane covers
- * whatever it cannot draw. `bypassFilters` + `showOk` reduce the filter to
- * exactly those floors — secret-bearing files, `.git`, `node_modules`,
- * `.ok/local`, reserved synthetic names — which is the same set the sidebar
- * refuses to show under Show All Files. Without a content filter there is no
- * floor to enforce, so nothing is offered.
- */
- function toOpenTarget(projectRelPath: string): GitWorktreeOpenTarget | undefined {
- const absPath = join(projectDir ?? contentDir, projectRelPath);
- const contentRelPath = toPosix(relative(contentDir, absPath));
- if (!contentRelPath || contentRelPath.startsWith('..')) return undefined;
- const docName = stripDocExtension(contentRelPath);
- if (getFileIndex().has(docName)) return { kind: 'doc', docName };
- if (!contentFilter) return undefined;
- if (contentFilter.isExcluded(contentRelPath, { bypassFilters: true, showOk: true })) {
- return undefined;
- }
- // A deletion, or an incoming file that has not landed yet: the viewer would
- // open on nothing. Docs skip this check — index membership implies the file.
- if (!existsSync(absPath)) return undefined;
- return { kind: 'asset', path: contentRelPath };
- }
-
- /**
- * `GET /api/git/worktree-status` — the `git status` view the sync popover
- * renders under its action buttons.
+ * Loopback-only via `checkLocalOpSecurity` — the handler spawns child
+ * processes (`open` / `start` / `xdg-open`) and writes to the user's
+ * `~/Downloads`, which is squarely state-mutating.
*
- * Kept off the `sync-status` payload deliberately: that one is pushed over
- * CC1 on every engine transition, and a working-tree listing does not belong
- * on a hot broadcast channel. This is polled by the popover while it is open.
+ * Request body (optional JSON): `{ noOpen?: boolean, out?: string }`.
+ * Response: the `BuildAndOpenSkillResult` shape verbatim.
*/
- async function handleGitWorktreeStatus(req: IncomingMessage, res: ServerResponse): Promise<void> {
- if (!checkLocalOpSecurity(req, res, { handler: 'git-worktree-status' })) return;
- if (req.method !== 'GET') {
- errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {
- handler: 'git-worktree-status',
- extraHeaders: { Allow: 'GET' },
- });
- return;
- }
- try {
- const engine = getSyncEngine?.();
- // Without an engine there is no admission predicate to mark scope with.
- // Report every path as out-of-scope rather than guessing in-scope: an
- // unmarked path the user then watches Push ignore is the worse failure.
- const isSyncScoped = engine
- ? (relPath: string) => engine.isSyncScopedPath(relPath)
- : () => false;
- const status = await readWorktreeStatus(projectDir ?? contentDir, isSyncScoped, toOpenTarget);
- successResponse(res, 200, GitWorktreeStatusSuccessSchema, status, {
- handler: 'git-worktree-status',
- });
- } catch (e) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: 'git-worktree-status',
- cause: e,
- });
- }
- }
-
- const handleSyncTrigger = withValidation(
- SyncTriggerRequestSchema,
+ const handleInstallSkill = withValidation(
+ InstallSkillRequestSchema,
async (_req, res, body) => {
- const engine = getSyncEngine?.();
- if (!engine) {
- // Race-window guard: the preBodyGate confirmed the engine was active,
- // but it could have been torn down between gate and inner-handler
- // invocation. Treat as 503 — same as the gate would have.
- errorResponse(res, 503, 'urn:ok:error:sync-not-active', 'Sync engine not active.', {
- handler: 'sync-trigger',
- });
- return;
- }
- const op = body.op ?? 'sync';
- // Fire-and-return: 202 Accepted immediately, trigger runs in background.
- successResponse(res, 202, SyncTriggerSuccessSchema, { op }, { handler: 'sync-trigger' });
- // `.catch` is mandatory on every fire-and-forget trigger: the response has
- // already been sent, so a rejection has nowhere to go but the process.
- void engine.trigger(op).catch((err) => {
- log.error({ err, op }, '[sync] fire-and-forget trigger failed');
- });
- },
- {
- handler: 'sync-trigger',
- method: 'POST',
- preBodyGate: (req, res) => {
- if (!checkLocalOpSecurity(req, res, { handler: 'sync-trigger' })) return false;
- const engine = getSyncEngine?.();
- if (!engine) {
- errorResponse(res, 503, 'urn:ok:error:sync-not-active', 'Sync engine not active.', {
- handler: 'sync-trigger',
- });
- return false;
- }
- return true;
- },
- },
- );
-
- /**
- * `POST /api/sync/resolve-blocking` — clear a pre-merge overlap pause by
- * committing the local edits that caused it, then resume.
- *
- * The body names an ACTION and nothing else. The paths come from the
- * engine's blocking set, so this cannot be aimed: a body-supplied path list
- * would make `discard` a general-purpose "throw away this file's edits"
- * endpoint reachable from any page the user's browser has open. Empty set →
- * 409 rather than a silent success, because a UI offering these buttons
- * against a pause that already cleared is showing the user stale state.
- *
- * The follow-up trigger is the point of the button: `commit` runs a full
- * sync, because the commit it just authored is now outgoing work.
- *
- * `commit` is the only action the schema admits. A `discard` verb is
- * deliberately withheld until a recoverable snapshot exists behind it —
- * restoring the blocking paths leaves no reflog entry to recover from.
- */
- const handleSyncResolveBlocking = withValidation(
- SyncResolveBlockingRequestSchema,
- // `body` is unread: the schema admits exactly one action, and the paths come
- // from engine state rather than the request (see the docblock above).
- async (_req, res, _body) => {
- const engine = getSyncEngine?.();
- if (!engine) {
- errorResponse(res, 503, 'urn:ok:error:sync-not-active', 'Sync engine not active.', {
- handler: 'sync-resolve-blocking',
- });
- return;
- }
- if (engine.getBlockingPaths().length === 0) {
+ // `out` flows into `path.resolve()` + `mkdir({recursive: true})` +
+ // `spawn('cmd', ['/c', 'start', '""', skillPath])` on Windows. Confine
+ // to $HOME consistent with the sibling local-op handler
+ // (`handleLocalOpClone`). Stays as post-validation business logic rather
+ // than a `.refine()` on the schema so the URN remains the more accurate
+ // `invalid-request` (the schema-shape `.refine()` rejection would also
+ // route through `urn:ok:error:invalid-request` but with a generic
+ // field-path message instead of this domain-specific title).
+ if (body.out !== undefined && !isSafeLocalPath(body.out)) {
errorResponse(
res,
- 409,
- 'urn:ok:error:no-blocking-changes',
- 'No local changes are blocking a merge.',
- {
- handler: 'sync-resolve-blocking',
- },
+ 400,
+ 'urn:ok:error:invalid-request',
+ 'Output path must be within home directory.',
+ { handler: 'install-skill' },
);
return;
}
+
try {
- // `commit` is the only action. A `discard` verb was deliberately not
- // shipped: reverting uncommitted work is unrecoverable (git keeps no
- // reflog for it), and the destructive verb waits on a recoverable
- // snapshot landing first. The schema rejects anything else before this
- // point, so there is no second branch to fall through to.
- const paths = engine.getBlockingPaths();
- const commitSha = await engine.commitBlockingPaths();
- successResponse(
- res,
- 200,
- SyncResolveBlockingSuccessSchema,
- { action: 'commit', paths, ...(commitSha !== null ? { commitSha } : {}) },
- { handler: 'sync-resolve-blocking' },
- );
- void engine.trigger('sync').catch((err) => {
- log.error({ err }, '[sync] resolve-blocking follow-up sync failed');
+ const result = await buildAndOpenSkill({
+ ...(body.noOpen !== undefined ? { noOpen: body.noOpen } : {}),
+ ...(body.out !== undefined ? { out: body.out } : {}),
});
- } catch (e) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: 'sync-resolve-blocking',
- cause: e,
+ successResponse(res, 200, InstallSkillSuccessSchema, result, {
+ handler: 'install-skill',
});
- }
- },
- {
- handler: 'sync-resolve-blocking',
- method: 'POST',
- preBodyGate: (req, res) =>
- checkLocalOpSecurity(req, res, { handler: 'sync-resolve-blocking' }),
- },
- );
-
- async function handleSyncConflicts(req: IncomingMessage, res: ServerResponse): Promise<void> {
- if (!checkLocalOpSecurity(req, res, { handler: 'sync-conflicts' })) return;
- if (req.method !== 'GET') {
- errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {
- handler: 'sync-conflicts',
- extraHeaders: { Allow: 'GET' },
- });
- return;
- }
- try {
- const engine = getSyncEngine?.();
- const conflicts = engine ? engine.getConflicts() : [];
- successResponse(
- res,
- 200,
- SyncConflictsSuccessSchema,
- { conflicts },
- {
- handler: 'sync-conflicts',
- },
- );
- } catch (e) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: 'sync-conflicts',
- cause: e,
- });
- }
- }
-
- const handleSyncResolveConflict = withValidation(
- SyncResolveConflictRequestSchema,
- async (_req, res, body) => {
- const engine = getSyncEngine?.();
- if (!engine) {
- // Race-window guard — see HANDLE_SYNC_TRIGGER comment.
- errorResponse(res, 503, 'urn:ok:error:sync-not-active', 'Sync engine not active.', {
- handler: 'sync-resolve-conflict',
+ } catch (err) {
+ // Generic title — raw `err.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 install skill.', {
+ handler: 'install-skill',
+ cause: err,
});
- return;
- }
- const { file, strategy, content } = body;
- try {
- await engine.resolveConflict(file, strategy as ResolveStrategy, content);
- successResponse(
- res,
- 200,
- SyncResolveConflictSuccessSchema,
- {},
- {
- handler: 'sync-resolve-conflict',
- },
- );
- } catch (e) {
- // Surface the underlying error (typically the git commit stderr
- // wrapped by `ConflictStore.resolveConflict`) on the RFC 9457
- // `detail` field so operators + UI toasts + agent tools have the
- // diagnostic context — without this, every commit failure looks
- // identical at the client.
- const detail = e instanceof Error ? e.message : undefined;
- errorResponse(
- res,
- 500,
- 'urn:ok:error:internal-server-error',
- 'Failed to resolve conflict.',
- {
- handler: 'sync-resolve-conflict',
- cause: e,
- detail,
- },
- );
}
},
{
- handler: 'sync-resolve-conflict',
+ handler: 'install-skill',
method: 'POST',
- preBodyGate: (req, res) => {
- if (!checkLocalOpSecurity(req, res, { handler: 'sync-resolve-conflict' })) return false;
- const engine = getSyncEngine?.();
- if (!engine) {
- errorResponse(res, 503, 'urn:ok:error:sync-not-active', 'Sync engine not active.', {
- handler: 'sync-resolve-conflict',
- });
- return false;
- }
- return true;
- },
+ preBodyGate: (req, res) => checkLocalOpSecurity(req, res, { handler: 'install-skill' }),
},
);
- async function handleSyncConflictContent(
- req: IncomingMessage,
+ function validateFolderRel(
+ raw: string,
res: ServerResponse,
- ): Promise<void> {
- if (!checkLocalOpSecurity(req, res, { handler: 'sync-conflict-content' })) return;
- if (req.method !== 'GET') {
- errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {
- handler: 'sync-conflict-content',
- extraHeaders: { Allow: 'GET' },
- });
- return;
- }
- if (!projectDir) {
- errorResponse(
- res,
- 503,
- 'urn:ok:error:project-repo-not-configured',
- 'Project repo not configured.',
- { handler: 'sync-conflict-content' },
- );
- return;
- }
- const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
- const file = url.searchParams.get('file');
- if (!file) {
+ label: 'path' | 'folder' = 'path',
+ handler = 'folder-config',
+ ): { folderRel: string; resolvedContentDir: string } | null {
+ const folderRel = raw.replace(/^\.\//, '').replace(/^\/+/, '').replace(/\/+$/, '');
+ if (folderRel.split('/').some((seg) => seg === '..') || raw.startsWith('/')) {
errorResponse(
res,
400,
'urn:ok:error:invalid-request',
- 'Missing required query param: file.',
- {
- handler: 'sync-conflict-content',
- },
+ `Invalid ${label}: must be project-root-relative.`,
+ { handler },
);
- return;
+ return null;
}
- // Reject obvious path-traversal; git itself rejects paths outside the index.
- if (file.includes('..') || file.startsWith('/')) {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid file path.', {
- handler: 'sync-conflict-content',
+ const resolvedContentDir = resolve(contentDir);
+ const candidateAbs =
+ folderRel === '' ? resolvedContentDir : resolve(resolvedContentDir, folderRel);
+ if (
+ candidateAbs !== resolvedContentDir &&
+ !candidateAbs.startsWith(`${resolvedContentDir}${sep}`)
+ ) {
+ errorResponse(res, 400, 'urn:ok:error:path-escape', 'Path escapes content directory.', {
+ handler,
});
- return;
- }
- // Refuse the request when no conflict is tracked for the path. Without
- // this gate, the git stage reads silently return empty strings for
- // untracked files, producing a 200 response with empty base/ours/theirs
- // — misleading to agents that took the file path from a stale 409
- // envelope or have inconsistent state. The tool description on
- // `conflicts({ kind: 'content' })` documents this 404; the gate enforces it.
- //
- // Authority is split between two sources that normally agree but can
- // diverge in tests / external-git scenarios: (a) ConflictStore via the
- // SyncEngine — populated when SyncEngine merges; and (b) the doc's
- // `lifecycle.status` Y.Map — set by the file-watcher's `case 'conflict'`
- // branch even when SyncEngine wasn't involved (markers landed on disk
- // via external git ops). Accept EITHER as authoritative tracking.
- const trackedDocName = stripDocExtension(file);
- const loadedDoc = hocuspocus.documents.get(trackedDocName);
- const isConflictedByLifecycle = loadedDoc?.getMap('lifecycle').get('status') === 'conflict';
- const engine = getSyncEngine?.();
- const isTrackedByStore = engine ? engine.getConflicts().some((c) => c.file === file) : false;
- if (!isConflictedByLifecycle && !isTrackedByStore) {
- errorResponse(
- res,
- 404,
- 'urn:ok:error:no-conflict-tracked',
- 'No conflict is tracked for this path.',
- {
- handler: 'sync-conflict-content',
- extensions: { file },
- },
- );
- return;
- }
- // Optional `?source=ytext` override: when the requested file maps to
- // a loaded doc, serve `ours` from the live Y.Text snapshot rather
- // than the git index. Covers the pre-conflict-unflushed-edits case
- // where Y.Text holds bytes the user typed after the last persistence
- // flush (persistence-during-conflict skip means those bytes don't
- // reach disk during conflict). Any other value (or no value) falls
- // back to the default `git show :2:` path so existing callers stay
- // backward-compatible.
- const source = url.searchParams.get('source');
- const pg = simpleGit({ baseDir: projectDir, timeout: { block: 15_000 } });
-
- // Working-tree-variant conflicts (pull-only B1) have no git index stages:
- // the branch already fast-forwarded to origin tip and the overlay rides
- // uncommitted on top. Serve `theirs`/`base` from the pinned tip/base blobs
- // and `ours` from the live doc (or disk when unloaded). The merge-native
- // stage path below is untouched for git-merge conflicts.
- const wtEntry = engine
- ?.getConflicts()
- .find((c) => c.file === file && c.variant === 'working-tree');
- if (wtEntry) {
- try {
- // A pinned SHA that fails to read is an unexpected failure (the blob was
- // reachable when the engine pinned it), NOT an absent blob. Returning ''
- // would misread it downstream as origin-deleted (`kind: 'modify-delete'`)
- // and steer the user into a `delete` resolution that removes their own
- // doc. Discriminate: `undefined` sha = genuinely no pinned blob (the
- // empty side of a delete/modify); a read failure on a present sha logs
- // and rethrows to the outer catch → 500, matching the merge-native
- // `showStage` discipline below.
- const readBlob = async (sha: string | undefined): Promise<string> => {
- if (!sha) return '';
- try {
- return await pg.raw(['cat-file', 'blob', sha]);
- } catch (err) {
- console.warn(
- JSON.stringify({
- event: 'conflict-content-readblob-failed',
- file,
- detail: err instanceof Error ? err.message : String(err),
- handler: 'sync-conflict-content',
- }),
- );
- throw err;
- }
- };
- const theirs = await readBlob(wtEntry.theirsSha);
- const base = await readBlob(wtEntry.baseSha);
- const docName = stripDocExtension(file);
- const loaded = hocuspocus.documents.get(docName);
- let ours = '';
- let oursPresent = false;
- let lifecycleStatus: string | null = null;
- if (loaded) {
- const rawStatus = loaded.getMap('lifecycle').get('status');
- lifecycleStatus =
- typeof rawStatus === 'string' && rawStatus.length > 0 ? rawStatus : null;
- const ytextOurs = serializeDoc ? serializeDoc(docName) : null;
- if (ytextOurs !== null) {
- ours = ytextOurs;
- oursPresent = true;
- }
- } else {
- // Unloaded doc: the overlay is on disk (absent for a delete overlay).
- // Realpath-contain the read first — `file` is an origin-controlled
- // tracked path that could be a symlink escaping the working tree,
- // disclosing a foreign file. A SymlinkEscapeError propagates to the
- // outer catch → 500; the inner catch still handles the benign ENOENT
- // of a genuine delete overlay.
- // `allowShareableOkArtifact` matches the write sites in conflict-storage.
- // Without it a root-`.ok` conflict (now pinnable — `.ok/templates/*` is a
- // shareable artifact) throws SymlinkEscapeError here and surfaces as a
- // 500, wedging the project: the push gate holds while conflicts exist and
- // the conflict cannot be inspected to resolve it. `docs/.ok/...` was
- // unaffected, so a nested fixture would not have caught it.
- assertRealpathWithinDir(join(projectDir, file), projectDir, {
- allowShareableOkArtifact: isShareableOkArtifact,
- });
- try {
- ours = readFileSync(join(projectDir, file), 'utf-8');
- oursPresent = true;
- } catch {
- oursPresent = false;
- }
- }
- // A locally-deleted file the tip modified is a delete/modify shape;
- // otherwise both sides hold content.
- const kind: 'both-modified' | 'delete-modify' | 'modify-delete' = !oursPresent
- ? 'delete-modify'
- : theirs.length === 0
- ? 'modify-delete'
- : 'both-modified';
- successResponse(
- res,
- 200,
- SyncConflictContentSuccessSchema,
- { file, base, ours, theirs, kind, lifecycleStatus },
- { handler: 'sync-conflict-content' },
- );
- } catch (e) {
- errorResponse(
- res,
- 500,
- 'urn:ok:error:internal-server-error',
- 'Failed to read conflict content.',
- { handler: 'sync-conflict-content', cause: e },
- );
- }
- return;
- }
-
- // git stages: 1 = base, 2 = ours, 3 = theirs. Any may be missing for
- // delete/edit or add/add conflicts. Return a discriminated shape so the
- // caller can derive `kind` from stage presence — empty-string content is
- // otherwise indistinguishable from a legitimately-empty file, and the
- // earlier swallow-and-return-`''` shape silently mapped DU/UD into the
- // both-modified path.
- type StageResult = { present: false } | { present: true; content: string };
- // Discriminate "stage genuinely absent" (expected for DU/UD) from
- // "git subprocess failed" (transient: timeout, permissions, corruption).
- // Both map to `{ present: false }` and the caller derives `kind` from
- // it — without this discrimination, a transient git error silently
- // sets `kind` to `'delete-modify'`, the UI renders "Keep deletion" for
- // a file the user actually edited, and clicking it `git rm`s the file.
- // Log unexpected errors loudly so "user lost work after resolution"
- // incidents have a paper trail.
- async function showStage(stage: 1 | 2 | 3): Promise<StageResult> {
- try {
- return { present: true, content: await pg.raw(['show', `:${stage}:${file}`]) };
- } catch (err) {
- const msg = err instanceof Error ? err.message : String(err);
- // Expected "stage absent" git error shapes from simple-git's stderr
- // passthrough. Observed in practice:
- // - "pathspec '...' did not match any files known to git"
- // - "path '...' is in the index, but not at stage <N>"
- // - "path '...' exists on disk, but not in '<ref>'"
- // Full-phrase matches only — short fragments like "but not in"
- // alone could false-match unrelated git errors and silently
- // return `{ present: false }` for a real failure (data-loss
- // class). Locale-stable English fragments — git messages are
- // English-only.
- const isAbsent =
- /pathspec|did not match|exists on disk, but not in|is in the index, but not at stage/i.test(
- msg,
- );
- if (!isAbsent) {
- // Unexpected git failure (timeout, object corruption, permission,
- // EMFILE). Returning `{ present: false }` would drive `kind`
- // derivation downstream silently — a transient stage-2 failure
- // on a both-modified conflict would produce
- // `kind: 'delete-modify'`, the UI would render "Keep file
- // deleted" + "Restore with remote changes", and clicking
- // "Keep file deleted" would `git rm` a file the user edited.
- // Rethrow so the outer try converts to a 500;
- // the UI's `fetchFailed` state ("Couldn't load conflict
- // content — try reloading") handles it visibly.
- console.warn(
- JSON.stringify({
- event: 'showstage-unexpected-error',
- stage,
- file,
- detail: msg,
- handler: 'sync-conflict-content',
- }),
- );
- throw err;
- }
- return { present: false };
- }
- }
- try {
- const [baseResult, oursResult, theirsResult] = await Promise.all([
- showStage(1),
- showStage(2),
- showStage(3),
- ]);
- const base = baseResult.present ? baseResult.content : '';
- const theirs = theirsResult.present ? theirsResult.content : '';
- // Derive the stage-presence discriminator. Reaching this handler
- // requires the conflict-tracked guard above, so
- // at least one of stages 2/3 is always present — `neither` is
- // unreachable at runtime. The four branches are enumerated
- // explicitly (rather than collapsed into a trailing else) so the
- // `(false, false)` branch is self-documenting: it surfaces
- // `'both-modified'` as a defensive default; the caller branches
- // safely off that without a load-bearing assertNever.
- const kind: 'both-modified' | 'delete-modify' | 'modify-delete' =
- oursResult.present && theirsResult.present
- ? 'both-modified'
- : !oursResult.present && theirsResult.present
- ? 'delete-modify'
- : oursResult.present && !theirsResult.present
- ? 'modify-delete'
- : 'both-modified';
- let ours = oursResult.present ? oursResult.content : '';
- // Surface `lifecycleStatus` when the doc is loaded server-side so the
- // MCP `conflicts({ kind: 'content' })` caller can detect post-resolution state
- // (status === null after the conflict clears) without a second
- // round-trip. Only meaningful in the `source=ytext` branch — the
- // default `git show :2:` path is callable without a loaded doc.
- let lifecycleStatus: string | null = null;
- if (source === 'ytext') {
- const docName = stripDocExtension(file);
- const loaded = hocuspocus.documents.get(docName);
- if (loaded) {
- const rawStatus = loaded.getMap('lifecycle').get('status');
- lifecycleStatus =
- typeof rawStatus === 'string' && rawStatus.length > 0 ? rawStatus : null;
- // Gate the Y.Text substitution on the `kind` shape. The narrow
- // risk that motivated the gate: for DU (delete-modify, stage 2
- // absent), the file-watcher seeded Y.Text with `theirs` content
- // from disk (git leaves the remote version in the working tree
- // on modify/delete conflicts). Substituting Y.Text into `ours`
- // would equal `theirs` and silently un-delete the local intent.
- // Honest path for DU: leave `ours` empty; the `kind` discriminator
- // drives the UI affordance.
- //
- // For every OTHER shape — both-modified (real merge), modify-
- // delete (stage 2 present, only theirs absent), and the legacy
- // filesystem-marker conflict path (neither stage in git index;
- // `case 'conflict'` in the file-watcher fires on disk-markers
- // without a real merge) — Y.Text substitution is correct and
- // load-bearing. A previous `oursResult.present` gate over-
- // restricted: it broke the filesystem-marker case where a
- // mid-conflict Y.Text edit must surface despite no git stages
- // existing in the index.
- if (kind !== 'delete-modify') {
- const ytextOurs = serializeDoc ? serializeDoc(docName) : null;
- if (ytextOurs !== null && !ytextHasConflictMarkers(ytextOurs)) {
- ours = ytextOurs;
- } else if (ytextOurs !== null) {
- // Structured signal so triage can spot when the marker-triple
- // detection fired and the handler fell back to git-index — the
- // alternative is silent. Pairs with `doc.name` for the
- // affected document.
- console.warn(
- JSON.stringify({
- event: 'ytext-conflict-marker-detected',
- 'doc.name': docName,
- handler: 'sync-conflict-content',
- }),
- );
- }
- }
- } else {
- log.warn(
- { docName },
- `[conflict-content] doc ${docName} not loaded; lifecycleStatus unavailable`,
- );
- }
- }
- successResponse(
- res,
- 200,
- SyncConflictContentSuccessSchema,
- { file, base, ours, theirs, kind, lifecycleStatus },
- { handler: 'sync-conflict-content' },
- );
- } catch (e) {
- errorResponse(
- res,
- 500,
- 'urn:ok:error:internal-server-error',
- 'Failed to read conflict content.',
- {
- handler: 'sync-conflict-content',
- cause: e,
- },
- );
- }
- }
-
- /**
- * `POST /api/install-skill` — build `openknowledge.skill` and open it via
- * the OS file association so Claude Desktop's native install dialog takes
- * over. Web-host counterpart of the Electron `okDesktop.skill.buildAndOpen`
- * bridge — both delegate to `buildAndOpenSkill` in `skill-install.ts`.
- *
- * Loopback-only via `checkLocalOpSecurity` — the handler spawns child
- * processes (`open` / `start` / `xdg-open`) and writes to the user's
- * `~/Downloads`, which is squarely state-mutating.
- *
- * Request body (optional JSON): `{ noOpen?: boolean, out?: string }`.
- * Response: the `BuildAndOpenSkillResult` shape verbatim.
- */
- const handleInstallSkill = withValidation(
- InstallSkillRequestSchema,
- async (_req, res, body) => {
- // `out` flows into `path.resolve()` + `mkdir({recursive: true})` +
- // `spawn('cmd', ['/c', 'start', '""', skillPath])` on Windows. Confine
- // to $HOME consistent with the sibling local-op handler
- // (`handleLocalOpClone`). Stays as post-validation business logic rather
- // than a `.refine()` on the schema so the URN remains the more accurate
- // `invalid-request` (the schema-shape `.refine()` rejection would also
- // route through `urn:ok:error:invalid-request` but with a generic
- // field-path message instead of this domain-specific title).
- if (body.out !== undefined && !isSafeLocalPath(body.out)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- 'Output path must be within home directory.',
- { handler: 'install-skill' },
- );
- return;
- }
-
- try {
- const result = await buildAndOpenSkill({
- ...(body.noOpen !== undefined ? { noOpen: body.noOpen } : {}),
- ...(body.out !== undefined ? { out: body.out } : {}),
- });
- successResponse(res, 200, InstallSkillSuccessSchema, result, {
- handler: 'install-skill',
- });
- } catch (err) {
- // Generic title — raw `err.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 install skill.', {
- handler: 'install-skill',
- cause: err,
- });
- }
- },
- {
- handler: 'install-skill',
- method: 'POST',
- preBodyGate: (req, res) => checkLocalOpSecurity(req, res, { handler: 'install-skill' }),
- },
- );
-
- function validateFolderRel(
- raw: string,
- res: ServerResponse,
- label: 'path' | 'folder' = 'path',
- handler = 'folder-config',
- ): { folderRel: string; resolvedContentDir: string } | null {
- const folderRel = raw.replace(/^\.\//, '').replace(/^\/+/, '').replace(/\/+$/, '');
- if (folderRel.split('/').some((seg) => seg === '..') || raw.startsWith('/')) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- `Invalid ${label}: must be project-root-relative.`,
- { handler },
- );
- return null;
- }
- const resolvedContentDir = resolve(contentDir);
- const candidateAbs =
- folderRel === '' ? resolvedContentDir : resolve(resolvedContentDir, folderRel);
- if (
- candidateAbs !== resolvedContentDir &&
- !candidateAbs.startsWith(`${resolvedContentDir}${sep}`)
- ) {
- errorResponse(res, 400, 'urn:ok:error:path-escape', 'Path escapes content directory.', {
- handler,
- });
- return null;
+ return null;
}
// Canonical containment on top of the lexical prefix check above, which a
// symlinked directory defeats (`notes -> /outside` keeps every lexical
@@ -16316,745 +15638,6 @@ export function createApiExtension(
});
searchService.prewarm();
- /**
- * `POST /api/share/construct-url` — read the project's local git state and
- * emit a marketing-safe share URL (`https://openknowledge.ai/d/<base64url>`)
- * pinned to HEAD branch + the focused doc. Read-only against the working
- * tree: no commits, no pushes, no fetches, no `git ls-remote`.
- * Branch-existence is checked locally against `refs/remotes/origin/<branch>`;
- * the false-negative window (last fetch ran before the push) is acceptable;
- * the toast prompts the user to
- * push, the retry succeeds.
- *
- * Returns HTTP 200 with `{ok: false, error: code}` for the six business-
- * logic failures (no-remote, detached-head, branch-not-on-origin,
- * non-github-remote, invalid-path, unsupported-share-url) — DELIBERATE
- * departure from RFC 9457 for these branches. The Share UI maps each code to a per-toast string;
- * routing through 4xx would conflate share-flow outcomes with transport
- * errors the client retries differently. Transport-class failures
- * (loopback gate, payload-too-large, body-parse) still emit RFC 9457 via
- * `errorResponse`.
- */
- const handleShareConstructUrl = withValidation(
- ShareConstructUrlRequestSchema,
- async (_req, res, body) => {
- try {
- if (!projectDir) {
- emitShareConstructUrlLog('no-remote', { kind: body.kind });
- successResponse(
- res,
- 200,
- ShareConstructUrlResponseSchema,
- { ok: false, error: 'no-remote' },
- { handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
- );
- return;
- }
- // Path validation is kind-specific: doc paths always name a file
- // (non-empty); folder paths may target the content root (empty).
- const sharePath = body.kind === 'doc' ? body.docPath : body.folderPath;
- if (!isValidSharePath(sharePath, body.kind)) {
- emitShareConstructUrlLog('invalid-path', { kind: body.kind });
- successResponse(
- res,
- 200,
- ShareConstructUrlResponseSchema,
- { ok: false, error: 'invalid-path' },
- { handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
- );
- return;
- }
- const branch = readGitHeadBranch(projectDir);
- if (branch === null) {
- // Two upstream causes ride this branch: (a) detached HEAD — the
- // sender must check out a branch; (b) no `.git/HEAD` at all (not a
- // git repo) — also caught downstream by `readOriginGitHubRepo`
- // returning `no-remote`. Disambiguate via the origin lookup so the
- // toast says the right thing.
- const originPeek = readOriginGitHubRepo(projectDir);
- if (originPeek.kind === 'no-remote') {
- emitShareConstructUrlLog('no-remote', { kind: body.kind });
- successResponse(
- res,
- 200,
- ShareConstructUrlResponseSchema,
- { ok: false, error: 'no-remote' },
- { handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
- );
- return;
- }
- emitShareConstructUrlLog('detached-head', { kind: body.kind });
- successResponse(
- res,
- 200,
- ShareConstructUrlResponseSchema,
- { ok: false, error: 'detached-head' },
- { handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
- );
- return;
- }
- const origin = readOriginGitHubRepo(projectDir);
- if (origin.kind === 'no-remote') {
- emitShareConstructUrlLog('no-remote', { kind: body.kind });
- successResponse(
- res,
- 200,
- ShareConstructUrlResponseSchema,
- { ok: false, error: 'no-remote' },
- { handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
- );
- return;
- }
- // Known non-GitHub forges (gitlab, bitbucket) can't produce a GitHub
- // share URL. GitHub hosts — github.com AND GHES — are supported: the
- // builders below take `origin.host` and the receive side accepts the
- // enterprise host behind its trust gate.
- if (origin.kind === 'non-github') {
- emitShareConstructUrlLog('non-github-remote', { kind: body.kind });
- successResponse(
- res,
- 200,
- ShareConstructUrlResponseSchema,
- { ok: false, error: 'non-github-remote' },
- { handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
- );
- return;
- }
- const branchExists = branchExistsOnOrigin(projectDir, branch);
- if (!branchExists) {
- emitShareConstructUrlLog('branch-not-on-origin', {
- branchExists: false,
- kind: body.kind,
- });
- successResponse(
- res,
- 200,
- ShareConstructUrlResponseSchema,
- { ok: false, error: 'branch-not-on-origin', branch },
- { handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
- );
- return;
- }
- // content.dir relative to the repo root. `''` when `content.dir === '.'`
- // (the dominant case). `null` (distinct from `''`) means contentDir
- // escapes projectDir — a project misconfiguration that breaks the
- // content-root invariant; fail loud via the outer catch (→ 500) rather
- // than collapsing to `''`, which would silently mint a share link
- // pointing at the repo root instead of the (broken) content dir.
- const contentRel = toGitRelativePath(projectDir, contentDir);
- if (contentRel === null) {
- throw new Error('content dir is not contained within the project dir');
- }
- const repositorySharePath =
- contentRel === ''
- ? sharePath
- : sharePath === ''
- ? contentRel
- : `${contentRel}/${sharePath}`;
- let sharedUrl: string;
- if (body.kind === 'doc') {
- sharedUrl = buildGitHubBlobUrl(
- origin.host,
- origin.owner,
- origin.repo,
- branch,
- repositorySharePath,
- );
- } else {
- sharedUrl = buildGitHubTreeUrl(
- origin.host,
- origin.owner,
- origin.repo,
- branch,
- repositorySharePath,
- );
- }
- // Derive depth through the same canonical build + parse contract the
- // reader uses. For valid contentRel values this count equals a raw
- // slash split; the round-trip also validates the encoded URL before
- // minting the token.
- let shareUrl: string;
- try {
- const contentRootDepth =
- contentRel === ''
- ? 0
- : parseCanonicalGitHubShareUrl(
- buildGitHubTreeUrl(origin.host, origin.owner, origin.repo, branch, contentRel),
- ).targetSegments.length;
- shareUrl = `${SHARE_BASE_URL}${encodeShareUrl(sharedUrl, contentRootDepth)}`;
- } catch (err) {
- if (!(err instanceof InvalidShareUrlError)) throw err;
- emitShareConstructUrlLog('unsupported-share-url', { kind: body.kind });
- successResponse(
- res,
- 200,
- ShareConstructUrlResponseSchema,
- { ok: false, error: 'unsupported-share-url' },
- { handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
- );
- return;
- }
- const freshness = await computeShareFreshness(
- projectDir,
- branch,
- repositorySharePath,
- body.kind,
- );
- emitShareConstructUrlLog('ok', { branchExists: true, kind: body.kind, freshness });
- successResponse(
- res,
- 200,
- ShareConstructUrlResponseSchema,
- { ok: true, shareUrl, sharedUrl, branch, freshness },
- { handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
- );
- } catch (err) {
- // Defensive: a future dependency change might add a throwing branch,
- // and the structured 200 contract above would otherwise leak the throw as an
- // unhandled-rejection 500. Generic title — raw `err.message` could
- // include FS paths.
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: SHARE_CONSTRUCT_URL_HANDLER_TAG,
- cause: err,
- });
- }
- },
- {
- handler: SHARE_CONSTRUCT_URL_HANDLER_TAG,
- method: 'POST',
- preBodyGate: (req, res) =>
- checkLocalOpSecurity(req, res, { handler: SHARE_CONSTRUCT_URL_HANDLER_TAG }),
- },
- );
-
- /**
- * `GET /api/git/branch-info?branch=<targetBranch>&path=<path>` — batched
- * view of git state for the share-receive branch-switch dialog:
- * - `currentBranch` / `currentHeadSha` / `detached` — HEAD identity
- * - `shareTargetExists` — `git cat-file -e <ref>:<path>` against the
- * current ref (HEAD when detached)
- * - `dirtyConflicts` — `dirtyFilesOverlapWith(projectDir, targetBranch)`
- * - `branchIsLocal` — `git rev-parse --verify refs/heads/<targetBranch>`
- *
- * All four probes run in parallel via `Promise.all` to stay under the
- * P99 < 500ms NFR. Read-only — does NOT acquire `withParentLock` so
- * concurrent sync-engine writes don't serialize behind the dialog
- * probe.
- */
- const handleBranchInfo = withValidation(
- EmptyRequestSchema,
- async (req, res) => {
- try {
- if (!projectDir) {
- errorResponse(
- res,
- 500,
- 'urn:ok:error:internal-server-error',
- 'projectDir is not configured for this server.',
- { handler: BRANCH_INFO_HANDLER_TAG },
- );
- return;
- }
- const url = new URL(req.url ?? '', 'http://localhost');
- const branch = url.searchParams.get('branch');
- const path = url.searchParams.get('path');
- // `kind` defaults to 'doc' when absent — keeps the existing
- // branch-info callers (which omit it) green until later stories
- // thread it through the share-receive dialog.
- const kindParam = url.searchParams.get('kind');
- const kind: 'doc' | 'folder' = kindParam === 'folder' ? 'folder' : 'doc';
- if (!isValidBranchName(branch)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- 'branch query param missing or malformed.',
- { handler: BRANCH_INFO_HANDLER_TAG },
- );
- return;
- }
- if (!isValidBranchInfoPath(path, kind)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- 'path query param missing or malformed.',
- { handler: BRANCH_INFO_HANDLER_TAG },
- );
- return;
- }
- // The desktop sends the URL-derived repository coordinate explicitly.
- // V1 has no mount metadata and must never be re-rooted from receiver
- // config; v2 already projected its separate content target at decode.
- const info = await computeBranchInfo(projectDir, branch, path, kind);
- successResponse(res, 200, BranchInfoResponseSchema, info, {
- handler: BRANCH_INFO_HANDLER_TAG,
- });
- } catch (err) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: BRANCH_INFO_HANDLER_TAG,
- cause: err,
- });
- }
- },
- {
- handler: BRANCH_INFO_HANDLER_TAG,
- method: 'GET',
- skipBodyParse: true,
- },
- );
-
- /**
- * `POST /api/share/target-status` — receive-side verdict for a share link
- * whose target is missing on the receiver's current ref. Runs a targeted
- * `git fetch origin <branch>` (authenticated by the user's ambient git
- * credential helper, same as checkout's fetch; no explicit token injection)
- * bounded by a timeout, then classifies the miss from git's rename detection:
- * on-origin (the local ref was stale) / renamed (+ a new path verified to
- * resolve at the origin ref) / deleted / never-on-branch / unknown (fetch
- * failed). Fail-open: any error returns `unknown`, and the caller falls back
- * to today's guidance.
- *
- * Updates only remote-tracking refs, no CRDT mutation — so the
- * attribution-sweep meta-test exempts it (see EXEMPT_HANDLERS).
- */
- function projectRenamedShareTarget(
- repositoryPath: string,
- renamedRepositoryPath: string,
- contentRootDepth: number,
- ): { verdict: 'renamed'; renamedTo: string } | { verdict: 'unknown' } {
- const originalSegments = repositoryPath.split('/');
- const renamedSegments = renamedRepositoryPath.split('/');
- if (contentRootDepth >= originalSegments.length || contentRootDepth >= renamedSegments.length) {
- return { verdict: 'unknown' };
- }
- for (let index = 0; index < contentRootDepth; index += 1) {
- if (originalSegments[index] !== renamedSegments[index]) return { verdict: 'unknown' };
- }
- return { verdict: 'renamed', renamedTo: renamedSegments.slice(contentRootDepth).join('/') };
- }
-
- const handleShareTargetStatus = withValidation(
- ShareTargetStatusRequestSchema,
- async (_req, res, body) => {
- try {
- if (!projectDir) {
- errorResponse(
- res,
- 500,
- 'urn:ok:error:internal-server-error',
- 'projectDir is not configured for this server.',
- { handler: SHARE_TARGET_STATUS_HANDLER_TAG },
- );
- return;
- }
- // Validate the path shape before it reaches git's `<ref>:<path>`
- // ref-spec, mirroring the sibling share handlers (construct-url's
- // `isValidSharePath`, branch-info's `isValidBranchInfoPath`) —
- // precedent #55 content-scope predicate symmetry. Kind-aware: an empty
- // path is the folder-root sentinel, invalid for a doc; `..`, `.git`,
- // control chars, and backslashes are rejected so a malformed path can't
- // reach git and degrade the verdict classification.
- if (!isValidBranchInfoPath(body.path, body.kind)) {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'path is missing or malformed.', {
- handler: SHARE_TARGET_STATUS_HANDLER_TAG,
- });
- return;
- }
- const status = await computeShareTargetStatus(
- projectDir,
- body.branch,
- body.path,
- body.kind,
- {
- credentialConfig: buildSyncCredentialConfig(localOpCliArgs, {
- resetAmbient: shouldResetAmbientCredentials(projectDir),
- }),
- },
- );
- const contentStatus =
- status.verdict !== 'renamed' || body.contentRootDepth === undefined
- ? status
- : projectRenamedShareTarget(body.path, status.renamedTo, body.contentRootDepth);
- successResponse(res, 200, ShareTargetStatusResponseSchema, contentStatus, {
- handler: SHARE_TARGET_STATUS_HANDLER_TAG,
- });
- } catch (err) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: SHARE_TARGET_STATUS_HANDLER_TAG,
- cause: err,
- });
- }
- },
- {
- handler: SHARE_TARGET_STATUS_HANDLER_TAG,
- method: 'POST',
- preBodyGate: (req, res) =>
- checkLocalOpSecurity(req, res, { handler: SHARE_TARGET_STATUS_HANDLER_TAG }),
- },
- );
-
- /**
- * `POST /api/git/checkout` — share-receive branch-switch executor.
- *
- * Wrapped in `withParentLock` so checkout serializes against the
- * sync-engine's parent-git writes (precedent: every other parent-git
- * write goes through this primitive). The branch-info endpoint is
- * read-only and lock-free; checkout is the matching writer.
- *
- * Identity is threaded through `extractActorIdentity` for observability
- * only — checkout is a git-level operation with no CRDT mutation. The
- * attribution-sweep meta-test exempts this handler explicitly.
- *
- * HEAD watcher is NOT coupled to this endpoint. The 200 response means
- * `git checkout` completed; the CRDT transition (Y.Docs reset + CC1
- * `branch-switched` broadcast) runs independently when the HEAD
- * watcher's `onBatchBegin`/`onBatchEnd` cycle fires.
- */
- const handleCheckout = withValidation(
- CheckoutRequestSchema,
- async (_req, res, body) => {
- const bodyObj = body as unknown as Record<string, unknown>;
- const actor = extractActorIdentity(bodyObj, getPrincipal);
- if (actor.kind === 'invalid-summary') {
- errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {
- handler: CHECKOUT_HANDLER_TAG,
- });
- return;
- }
-
- if (!projectDir) {
- errorResponse(
- res,
- 500,
- 'urn:ok:error:internal-server-error',
- 'projectDir is not configured for this server.',
- { handler: CHECKOUT_HANDLER_TAG },
- );
- return;
- }
-
- try {
- const outcome = await withParentLock(() =>
- runCheckoutFlow(projectDir, body.branch, {
- fastForward: body.fastForward === true,
- credentialConfig: buildSyncCredentialConfig(localOpCliArgs, {
- resetAmbient: shouldResetAmbientCredentials(projectDir),
- }),
- }),
- );
- successResponse(res, 200, CheckoutResponseSchema, outcome, {
- handler: CHECKOUT_HANDLER_TAG,
- });
- } catch (err) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: CHECKOUT_HANDLER_TAG,
- cause: err,
- });
- }
- },
- {
- handler: CHECKOUT_HANDLER_TAG,
- method: 'POST',
- },
- );
-
- /**
- * Spawn the share-flow CLI subcommand once, with a bounded timeout, and
- * collect its stdout. Returns the captured text + exit code. Used by all
- * three publish handlers; the shape mirrors `handleLocalOpAuthStatus`'s
- * inline spawn so the route-shape meta-tests scan one consistent pattern.
- *
- * stderr is piped + collected; on non-zero exit, a redacted prefix is
- * logged via the `api` logger (`[share] subprocess ...`) so production
- * failures (git binary missing, keychain denied, Octokit auth error)
- * leave a diagnostic trail. Credential URLs of the form
- * `x-access-token:<token>@github.com` get the token replaced with `***`
- * before logging — the CLI uses inline-token push URLs and a partial git
- * error could otherwise leak the PAT.
- *
- * Throws on spawn-failure / timeout — the handlers map to `errorResponse`.
- */
- async function spawnShareSubprocess(
- args: readonly string[],
- ): Promise<{ stdout: string; code: number | null }> {
- const [cmd, ...baseArgs] = localOpCliArgs;
- const spawnArgs = [...baseArgs, ...args];
- return await new Promise<{ stdout: string; code: number | null }>((resolveSpawn, reject) => {
- const child = spawn(
- cmd,
- spawnArgs,
- withHiddenWindowsConsole({
- ...LOCAL_OP_PIPE_STDIO_OPTIONS,
- env: { ...process.env },
- }),
- );
- let timedOut = false;
- const killTimer = setTimeout(() => {
- timedOut = true;
- child.kill('SIGTERM');
- }, SHARE_PUBLISH_TIMEOUT_MS);
- const stdoutChunks: Buffer[] = [];
- const stderrChunks: Buffer[] = [];
- child.stdout.on('data', (chunk: Buffer) => stdoutChunks.push(chunk));
- child.stderr.on('data', (chunk: Buffer) => stderrChunks.push(chunk));
- child.on('close', (code) => {
- clearTimeout(killTimer);
- if (timedOut) {
- reject(new Error(`share subprocess timed out after ${SHARE_PUBLISH_TIMEOUT_MS}ms`));
- return;
- }
- const stdout = Buffer.concat(stdoutChunks).toString('utf-8');
- if (code !== 0) {
- const stderr = Buffer.concat(stderrChunks).toString('utf-8');
- const redacted = redactShareSubprocessStderr(stderr).slice(0, 500);
- log.warn(
- { code, stderr: redacted },
- `[share] subprocess exited code=${code} stderr=${redacted}`,
- );
- }
- resolveSpawn({ stdout, code });
- });
- child.on('error', (err) => {
- clearTimeout(killTimer);
- reject(err);
- });
- });
- }
-
- /**
- * GET /api/share/publish/owners — list GitHub owners the user can host a
- * new repo under (owner eligibility). Spawns `open-knowledge share owners --json` and
- * returns one of:
- * { ok: true, owners: [...] }
- * { ok: false, error: 'auth-required' | 'network' }
- *
- * The owners endpoint is read-only and idempotent; the localOpGuard slot
- * is shared with the wider publish flow so concurrent owner-list +
- * publish-create can't race against the same OAuth flow.
- */
- const handleSharePublishOwners = withValidation(
- EmptyRequestSchema,
- async (_req, res) => {
- if (!localOpGuard.tryAcquire(SHARE_PUBLISH_OWNERS_KEY)) {
- errorResponse(
- res,
- 429,
- 'urn:ok:error:concurrent-operation',
- 'A share owners operation is already in progress.',
- { handler: SHARE_PUBLISH_OWNERS_HANDLER_TAG, extraHeaders: { 'Retry-After': '5' } },
- );
- return;
- }
- try {
- const { stdout } = await spawnShareSubprocess(['share', 'owners', '--json']);
- const event = pickTerminalJsonLine(stdout);
- const body = parseOwnersEvent(event);
- emitSharePublishLog(
- 'owners-list',
- body.ok ? 'ok' : body.error,
- body.ok ? { count: body.owners.length } : undefined,
- );
- successResponse(res, 200, SharePublishOwnersResponseSchema, body, {
- handler: SHARE_PUBLISH_OWNERS_HANDLER_TAG,
- });
- } catch (err) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: SHARE_PUBLISH_OWNERS_HANDLER_TAG,
- cause: err,
- });
- } finally {
- localOpGuard.release(SHARE_PUBLISH_OWNERS_KEY);
- }
- },
- {
- handler: SHARE_PUBLISH_OWNERS_HANDLER_TAG,
- method: 'GET',
- skipBodyParse: true,
- preBodyGate: (req, res) =>
- checkLocalOpSecurity(req, res, { handler: SHARE_PUBLISH_OWNERS_HANDLER_TAG }),
- },
- );
-
- /**
- * GET /api/share/publish/name-check?owner=<o>&name=<n> — pre-flight a repo
- * name for conflict. Spawns `open-knowledge share name-check --json
- * --owner X --name Y` and returns one of:
- * { ok: true, available: boolean }
- * { ok: false, error: 'auth-required' | 'network' }
- *
- * Query-param validation runs server-side: missing/invalid `owner` or
- * `name` short-circuits to 400 invalid-request BEFORE the subprocess
- * spawns. This keeps a malformed wizard call from triggering a CLI
- * exec on every keypress.
- */
- const handleSharePublishNameCheck = withValidation(
- EmptyRequestSchema,
- async (req, res) => {
- const url = new URL(req.url ?? '', 'http://localhost');
- const owner = url.searchParams.get('owner') ?? '';
- const name = url.searchParams.get('name') ?? '';
- if (!isValidShareOwnerName(owner) || !isValidShareRepoName(name)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- 'owner and name query params must be valid GitHub identifiers.',
- { handler: SHARE_PUBLISH_NAME_CHECK_HANDLER_TAG },
- );
- return;
- }
- if (!localOpGuard.tryAcquire(SHARE_PUBLISH_NAME_CHECK_KEY)) {
- errorResponse(
- res,
- 429,
- 'urn:ok:error:concurrent-operation',
- 'A share name-check operation is already in progress.',
- { handler: SHARE_PUBLISH_NAME_CHECK_HANDLER_TAG, extraHeaders: { 'Retry-After': '5' } },
- );
- return;
- }
- try {
- const { stdout } = await spawnShareSubprocess([
- 'share',
- 'name-check',
- '--owner',
- owner,
- '--name',
- name,
- '--json',
- ]);
- const event = pickTerminalJsonLine(stdout);
- const body = parseNameCheckEvent(event);
- emitSharePublishLog(
- 'name-check',
- body.ok ? 'ok' : body.error,
- body.ok ? { available: body.available } : undefined,
- );
- successResponse(res, 200, SharePublishNameCheckResponseSchema, body, {
- handler: SHARE_PUBLISH_NAME_CHECK_HANDLER_TAG,
- });
- } catch (err) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: SHARE_PUBLISH_NAME_CHECK_HANDLER_TAG,
- cause: err,
- });
- } finally {
- localOpGuard.release(SHARE_PUBLISH_NAME_CHECK_KEY);
- }
- },
- {
- handler: SHARE_PUBLISH_NAME_CHECK_HANDLER_TAG,
- method: 'GET',
- skipBodyParse: true,
- preBodyGate: (req, res) =>
- checkLocalOpSecurity(req, res, { handler: SHARE_PUBLISH_NAME_CHECK_HANDLER_TAG }),
- },
- );
-
- /**
- * POST /api/share/publish — drive a no-remote project to first share (publish flow).
- * Spawns `open-knowledge share publish --json --owner ... --name ...
- * --visibility ... [--description ...] --project-dir <projectDir>` and
- * returns one of:
- * { ok: true, ownerLogin, repoName, cloneUrl, defaultBranch }
- * { ok: false, error: <SharePublishErrorCode> }
- *
- * `projectDir` is sourced from the server's own `ApiExtensionOptions` —
- * never trusted from the client — so a hostile caller can't redirect
- * the publish flow at another project on disk. Absent `projectDir`
- * surfaces as `no-project` (the editor's wizard knows what to do).
- */
- const handleSharePublish = withValidation(
- SharePublishRequestSchema,
- async (_req, res, body) => {
- if (!projectDir) {
- emitSharePublishLog('publish-create', 'no-project');
- successResponse(
- res,
- 200,
- SharePublishResponseSchema,
- { ok: false, error: 'no-project' },
- { handler: SHARE_PUBLISH_HANDLER_TAG },
- );
- return;
- }
- if (!isValidShareOwnerName(body.owner) || !isValidShareRepoName(body.name)) {
- errorResponse(
- res,
- 400,
- 'urn:ok:error:invalid-request',
- 'owner and name must be valid GitHub identifiers.',
- { handler: SHARE_PUBLISH_HANDLER_TAG },
- );
- return;
- }
- if (!localOpGuard.tryAcquire(SHARE_PUBLISH_KEY)) {
- errorResponse(
- res,
- 429,
- 'urn:ok:error:concurrent-operation',
- 'A share publish operation is already in progress.',
- { handler: SHARE_PUBLISH_HANDLER_TAG, extraHeaders: { 'Retry-After': '5' } },
- );
- return;
- }
- try {
- const args = [
- 'share',
- 'publish',
- '--owner',
- body.owner,
- '--name',
- body.name,
- '--visibility',
- body.visibility,
- '--project-dir',
- projectDir,
- '--json',
- ];
- if (body.description !== undefined && body.description.length > 0) {
- args.push('--description', body.description);
- }
- const { stdout } = await spawnShareSubprocess(args);
- const event = pickTerminalJsonLine(stdout);
- const responseBody = parsePublishEvent(event);
- emitSharePublishLog('publish-create', responseBody.ok ? 'ok' : responseBody.error);
- if (responseBody.ok) {
- // A successful publish just added `origin` to the local repo (the
- // CLI's runPublishFlow addRemote step). The sync engine snapshotted
- // `hasRemote: false` at boot, so without a nudge the client keeps
- // routing the Share button into THIS wizard — and the republish
- // 422s on the repo that now exists. Fire-and-forget re-detection
- // flips `hasRemote` and signals CC1 'sync-status' so the next Share
- // click constructs the URL directly. Mirrors the set-identity
- // handler's refreshIdentity nudge.
- void getSyncEngine?.()
- ?.refreshRemote()
- .catch(() => {
- /* best-effort — status catches up on next poll / restart */
- });
- }
- successResponse(res, 200, SharePublishResponseSchema, responseBody, {
- handler: SHARE_PUBLISH_HANDLER_TAG,
- });
- } catch (err) {
- errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
- handler: SHARE_PUBLISH_HANDLER_TAG,
- cause: err,
- });
- } finally {
- localOpGuard.release(SHARE_PUBLISH_KEY);
- }
- },
- {
- handler: SHARE_PUBLISH_HANDLER_TAG,
- method: 'POST',
- preBodyGate: (req, res) =>
- checkLocalOpSecurity(req, res, { handler: SHARE_PUBLISH_HANDLER_TAG }),
- },
- );
-
// ───────────────────── Embeddings API key — Account control ─────────────────
// Loopback + Origin gated (checkLocalOpSecurity) set/clear for the
// machine-global embeddings key. The key travels renderer → loopback POST body
@@ -17801,28 +16384,7 @@ export function createApiExtension(
{ handler: 'lint-fix', method: 'POST' },
);
- // The comment store + service are constructed near `resolveDocPath` above so
- // the rename walk can follow renames. Two dispatchers keep the surface to two
- // paths; the mutating sub-handlers in `comment-api.ts` thread
- // `extractActorIdentity` (same posture as the `handleSkill` / `handleTemplate`
- // dispatchers in the attribution sweep).
- const commentApi = createCommentApi({
- service: commentService,
- getPrincipal,
- onChanged: () => signalChannel?.('comments'),
- });
- const handleCommentsRoute = methodRouter(
- { GET: commentApi.list, POST: commentApi.create },
- { handler: 'comments' },
- );
- const handleCommentRoute = methodRouter(
- { GET: commentApi.read, POST: commentApi.mutate, DELETE: commentApi.remove },
- { handler: 'comment' },
- );
-
const routes: Record<string, (req: IncomingMessage, res: ServerResponse) => Promise<void>> = {
- '/api/comments': handleCommentsRoute,
- '/api/comment': handleCommentRoute,
'/api/asset': handleAsset,
'/api/asset-text': handleAssetText,
'/api/skill': handleSkill,
@@ -17855,20 +16417,6 @@ export function createApiExtension(
'/api/agent-burst-diff': handleAgentBurstDiff,
'/api/save-version': handleSaveVersion,
'/api/rollback': handleRollback,
- '/api/share/construct-url': handleShareConstructUrl,
- '/api/share/target-status': handleShareTargetStatus,
- '/api/git/branch-info': handleBranchInfo,
- '/api/git/worktree-status': handleGitWorktreeStatus,
- '/api/git/checkout': handleCheckout,
- '/api/share/publish/owners': handleSharePublishOwners,
- '/api/share/publish/name-check': handleSharePublishNameCheck,
- '/api/share/publish': handleSharePublish,
- '/api/sync/status': handleSyncStatus,
- '/api/sync/trigger': handleSyncTrigger,
- '/api/sync/conflicts': handleSyncConflicts,
- '/api/sync/conflict-content': handleSyncConflictContent,
- '/api/sync/resolve-conflict': handleSyncResolveConflict,
- '/api/sync/resolve-blocking': handleSyncResolveBlocking,
'/api/local-op/clone': handleLocalOpClone,
'/api/local-op/ok-init': handleLocalOpOkInit,
'/api/local-op/auth/login': handleLocalOpAuthLogin,
@@ -17899,8 +16447,6 @@ export function createApiExtension(
// UI can bootstrap against the collab server; mutations require a
// loopback Host header. /api/workspace enforces this inline already.
const MUTATING_ROUTES: ReadonlySet<string> = new Set([
- '/api/comments',
- '/api/comment',
'/api/lint/markdownlint-config',
'/api/lint/frontmatter-schema',
'/api/lint/fix',
@@ -17912,10 +16458,6 @@ export function createApiExtension(
'/api/agent-undo',
'/api/save-version',
'/api/rollback',
- '/api/sync/trigger',
- '/api/sync/resolve-conflict',
- '/api/sync/resolve-blocking',
- '/api/git/checkout',
'/api/test-reset',
'/api/test-flush-git',
'/api/test-rescan-backlinks',
@@ -18075,6 +16617,39 @@ export function createApiExtension(
getGeneratedIndexSettingsStatus,
setGeneratedIndexEnabled,
});
+ const commentRoutes = createCommentRoutes({
+ commentService,
+ getPrincipal,
+ signalChannel,
+ });
+ const syncRoutes = createSyncRoutes({
+ projectDir,
+ hocuspocus,
+ log,
+ checkLocalOpSecurity,
+ getSyncEngine,
+ serializeDoc,
+ });
+ const shareRoutes = createShareRoutes({
+ projectDir,
+ contentDir,
+ log,
+ checkLocalOpSecurity,
+ localOpCliArgs,
+ localOpGuard,
+ getSyncEngine,
+ toGitRelativePath,
+ });
+ const gitRoutes = createGitRoutes({
+ projectDir,
+ contentDir,
+ contentFilter,
+ getFileIndex,
+ checkLocalOpSecurity,
+ getSyncEngine,
+ getPrincipal,
+ localOpCliArgs,
+ });
const fileOpsRoutes = createFileOpsRoutes({
contentDir,
projectDir,
@@ -18152,6 +16727,10 @@ export function createApiExtension(
skillsReadRoutes,
skillsShRoutes,
workspaceToolsRoutes,
+ commentRoutes,
+ syncRoutes,
+ shareRoutes,
+ gitRoutes,
fileOpsRoutes,
seedRoutes,
systemActionsRoutes,
diff --git a/packages/server/src/api-git-composition.test.ts b/packages/server/src/api-git-composition.test.ts
new file mode 100644
index 000000000..3cc73ad08
--- /dev/null
+++ b/packages/server/src/api-git-composition.test.ts
@@ -0,0 +1,92 @@
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+import type { BootedServer } from './boot.ts';
+import { bootCompositionRig, parseProblem, rawRequest } from './composition-rig.test-helper.ts';
+
+/**
+ * Characterization: the natively-routed git group over a REAL socket through
+ * the composed `bootServer` stack — native registration and the shared
+ * admission posture. Gate BEHAVIOR is owned by
+ * `api-admission-composition.test.ts` (path-agnostic by construction); the
+ * rebound-Host pin below re-pins gate REACHABILITY for this family — a
+ * native-registration bug could mount the group outside
+ * `createApiRequestPipeline` without changing any happy-path response, and a
+ * hostile-header probe is the only wire signal that tells those apart. The
+ * wire cannot distinguish the mutating gate from the read gate (both apply
+ * the same loopback + workspace-Host checks), so the mutating DECLARATION
+ * itself is pinned at the table tier in `http/git-routes.test.ts`.
+ *
+ * The rig's content dir is not a git repository: branch-info and checkout
+ * refuse on validation before any git op, and worktree-status degrades to its
+ * unreadable-porcelain 200 — all real-handler responses, no git side effects.
+ */
+
+let tmpRoot: string;
+let server: BootedServer;
+
+beforeAll(async () => {
+ tmpRoot = await mkdtemp(resolve(tmpdir(), 'ok-git-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('git group over the composed listener — served natively', () => {
+ test('every route in the group is registered natively (wrong verb → 405, not a route-miss 404)', async () => {
+ for (const path of ['/api/git/branch-info', '/api/git/worktree-status']) {
+ 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');
+ }
+ const checkout = await fetch(`http://127.0.0.1:${server.port}/api/git/checkout`);
+ expect(checkout.status).toBe(405);
+ expect(checkout.headers.get('allow')).toBe('POST');
+ });
+
+ test('branch-info refuses missing params with its own 400 before any git op', async () => {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/git/branch-info`);
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:invalid-request');
+ expect(res.headers.get('x-request-id')).not.toBeNull();
+ });
+
+ test('worktree-status reaches the real handler (200 on a non-repo content dir)', async () => {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/git/worktree-status`);
+ expect(res.status).toBe(200);
+ });
+
+ test('checkout refuses a malformed body with its own 400 before any git op', async () => {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/git/checkout`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: '{}',
+ });
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:invalid-request');
+ });
+
+ test('checkout refuses a rebound Host with 403 (loopback/host gate survives the lift)', async () => {
+ const res = await rawRequest(server.port, '/api/git/checkout', {
+ method: 'POST',
+ headers: { Host: 'evil.example' },
+ });
+ expect(res.status).toBe(403);
+ expect(parseProblem(res.body).type).toBe('urn:ok:error:host-not-allowed');
+ });
+
+ test('chained groups still 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 branchInfo = await fetch(`http://127.0.0.1:${server.port}/api/git/branch-info`);
+ expect(branchInfo.status).toBe(400);
+ });
+});
diff --git a/packages/server/src/api-share-composition.test.ts b/packages/server/src/api-share-composition.test.ts
new file mode 100644
index 000000000..d033abdbe
--- /dev/null
+++ b/packages/server/src/api-share-composition.test.ts
@@ -0,0 +1,126 @@
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+import type { BootedServer } from './boot.ts';
+import { bootCompositionRig, parseProblem, rawRequest } from './composition-rig.test-helper.ts';
+
+/**
+ * Characterization: the natively-routed share group over a REAL socket
+ * through the composed `bootServer` stack — native registration and the
+ * shared admission posture. Gate BEHAVIOR is owned by
+ * `api-admission-composition.test.ts` (path-agnostic by construction); the
+ * rebound-Host pins below re-pin gate REACHABILITY for this family — a
+ * native-registration bug could mount the group outside
+ * `createApiRequestPipeline` without changing any happy-path response, and a
+ * hostile-header probe is the only wire signal that tells those apart. The
+ * group's EMPTY mutating declaration (`share/publish` deliberately excluded)
+ * is pinned at the table tier in `http/share-routes.test.ts`.
+ *
+ * Every request below refuses BEFORE any git subprocess or GitHub egress —
+ * wrong verb, invalid identifiers, or the no-git-repo fallbacks — so the
+ * suite never spawns the share CLI.
+ */
+
+const ALL_ROUTES = [
+ '/api/share/construct-url',
+ '/api/share/target-status',
+ '/api/share/publish/owners',
+ '/api/share/publish/name-check',
+ '/api/share/publish',
+];
+
+let tmpRoot: string;
+let server: BootedServer;
+
+beforeAll(async () => {
+ tmpRoot = await mkdtemp(resolve(tmpdir(), 'ok-share-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('share group over the composed listener — served natively', () => {
+ test('every route in the group is registered natively (wrong verb → 405, not a route-miss 404)', async () => {
+ for (const path of [
+ '/api/share/construct-url',
+ '/api/share/target-status',
+ '/api/share/publish',
+ ]) {
+ const res = await fetch(`http://127.0.0.1:${server.port}${path}`);
+ expect(res.status, path).toBe(405);
+ expect(res.headers.get('allow'), path).toBe('POST');
+ }
+ for (const path of ['/api/share/publish/owners', '/api/share/publish/name-check']) {
+ 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('construct-url reaches the real handler (no-git-repo → structured 200 no-remote)', async () => {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/share/construct-url`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ kind: 'doc', docPath: 'alpha.md' }),
+ });
+ expect(res.status).toBe(200);
+ expect(await res.json()).toEqual({ ok: false, error: 'no-remote' });
+ });
+
+ test('name-check refuses malformed identifiers with its own 400 before any subprocess', async () => {
+ const res = await fetch(
+ `http://127.0.0.1:${server.port}/api/share/publish/name-check?owner=-bad-&name=x`,
+ );
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:invalid-request');
+ expect(res.headers.get('x-request-id')).not.toBeNull();
+ });
+
+ test('publish refuses malformed identifiers with its own 400 before any subprocess', async () => {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/share/publish`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ owner: '-bad-', name: 'x', visibility: 'private' }),
+ });
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:invalid-request');
+ });
+
+ test('target-status refuses a malformed path with its own 400 before any git op', async () => {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/share/target-status`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ branch: 'main', path: '../escape.md', kind: 'doc' }),
+ });
+ expect(res.status).toBe(400);
+ expect(((await res.json()) as { type?: string }).type).toBe('urn:ok:error:invalid-request');
+ });
+
+ test('a rebound Host is refused on every route (shared gate survives the lift)', async () => {
+ for (const path of ALL_ROUTES) {
+ const res = await rawRequest(server.port, path, {
+ method: 'POST',
+ headers: { Host: 'evil.example' },
+ });
+ expect(res.status, path).toBe(403);
+ expect(parseProblem(res.body).type, path).toBe('urn:ok:error:host-not-allowed');
+ }
+ });
+
+ test('chained groups still 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 nameCheck = await fetch(
+ `http://127.0.0.1:${server.port}/api/share/publish/name-check?owner=-bad-&name=x`,
+ );
+ expect(nameCheck.status).toBe(400);
+ });
+});
diff --git a/packages/server/src/api-sync-composition.test.ts b/packages/server/src/api-sync-composition.test.ts
new file mode 100644
index 000000000..7eb6ad7ff
--- /dev/null
+++ b/packages/server/src/api-sync-composition.test.ts
@@ -0,0 +1,105 @@
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+import type { BootedServer } from './boot.ts';
+import { bootCompositionRig, parseProblem, rawRequest } from './composition-rig.test-helper.ts';
+
+/**
+ * Characterization: the natively-routed sync group over a REAL socket through
+ * the composed `bootServer` stack — native registration and the shared
+ * admission posture. Gate BEHAVIOR is owned by
+ * `api-admission-composition.test.ts` (path-agnostic by construction); the
+ * rebound-Host pin below re-pins gate REACHABILITY for this family — a
+ * native-registration bug could mount the group outside
+ * `createApiRequestPipeline` without changing any happy-path response, and a
+ * hostile-header probe is the only wire signal that tells those apart. The
+ * wire cannot distinguish the mutating gate from the read gate (both apply
+ * the same loopback + workspace-Host checks), so the mutating DECLARATION
+ * itself is pinned at the table tier in `http/sync-routes.test.ts`.
+ *
+ * The rig boots with `gitEnabled: false`: the engine is wired but never syncs
+ * (no remote, git preflight skipped), so the dormant status, empty conflicts,
+ * and fire-and-return 202 below are exactly the real handlers' responses,
+ * proving dispatch reaches them without any git subprocess reaching a remote.
+ */
+
+/** The mutating trio — legacy `MUTATING_ROUTES` members (declaration pinned in the table suite). */
+const MUTATING_ROUTES = [
+ '/api/sync/trigger',
+ '/api/sync/resolve-conflict',
+ '/api/sync/resolve-blocking',
+];
+
+let tmpRoot: string;
+let server: BootedServer;
+
+beforeAll(async () => {
+ tmpRoot = await mkdtemp(resolve(tmpdir(), 'ok-sync-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('sync group over the composed listener — served natively', () => {
+ test('reads answer with their real engine-absent fallbacks (dormant status, empty conflicts)', async () => {
+ const status = await fetch(`http://127.0.0.1:${server.port}/api/sync/status`);
+ expect(status.status).toBe(200);
+ expect(((await status.json()) as { state?: string }).state).toBe('dormant');
+ const conflicts = await fetch(`http://127.0.0.1:${server.port}/api/sync/conflicts`);
+ expect(conflicts.status).toBe(200);
+ expect(await conflicts.json()).toEqual({ conflicts: [] });
+ });
+
+ test('reads refuse the wrong verb with their own 405 (POST → 405 + Allow: GET)', async () => {
+ for (const path of ['/api/sync/status', '/api/sync/conflicts', '/api/sync/conflict-content']) {
+ 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('mutating trio is registered natively (GET → 405 + Allow: POST, x-request-id echoed)', async () => {
+ for (const path of MUTATING_ROUTES) {
+ const res = await fetch(`http://127.0.0.1:${server.port}${path}`);
+ expect(res.status, path).toBe(405);
+ expect(res.headers.get('allow'), path).toBe('POST');
+ expect(res.headers.get('x-request-id'), path).not.toBeNull();
+ }
+ });
+
+ test('a mutating POST reaches the real handler (202 fire-and-return from the wired engine)', async () => {
+ const res = await fetch(`http://127.0.0.1:${server.port}/api/sync/trigger`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: '{}',
+ });
+ expect(res.status).toBe(202);
+ expect(await res.json()).toEqual({ op: 'sync' });
+ });
+
+ test('mutating trio refuses a rebound Host with 403 (loopback/host gate survives the lift)', async () => {
+ for (const path of MUTATING_ROUTES) {
+ const res = await rawRequest(server.port, path, {
+ method: 'POST',
+ headers: { Host: 'evil.example' },
+ });
+ expect(res.status, path).toBe(403);
+ expect(parseProblem(res.body).type, path).toBe('urn:ok:error:host-not-allowed');
+ }
+ });
+
+ test('chained groups still 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 status = await fetch(`http://127.0.0.1:${server.port}/api/sync/status`);
+ expect(status.status).toBe(200);
+ });
+});
diff --git a/packages/server/src/child-process-windows-hide.ts b/packages/server/src/child-process-windows-hide.ts
index 87dd9a8d6..09e914e09 100644
--- a/packages/server/src/child-process-windows-hide.ts
+++ b/packages/server/src/child-process-windows-hide.ts
@@ -1,5 +1,19 @@
export type HiddenWindowsConsoleOptions<T extends object> = T & { windowsHide: true };
+/**
+ * The piped local-op spawn stdio shape (stdin ignored, stdout + stderr piped
+ * for capture) — the one member of the extension's stdio-shape family that
+ * grew a second consumer when the share family lifted out. Shared from here —
+ * the module both `api-extension.ts` and `http/share-routes.ts` already
+ * import for {@link withHiddenWindowsConsole} — so the shape has one
+ * declaration rather than per-call-site copies that can silently drift. The
+ * extension's other stdio shapes (stderr-only, fully-ignored) stay local to
+ * their single call sites.
+ */
+export const LOCAL_OP_PIPE_STDIO_OPTIONS: { stdio: ['ignore', 'pipe', 'pipe'] } = {
+ stdio: ['ignore', 'pipe', 'pipe'],
+};
+
/**
* GUI-launched Windows server processes have no inherited console. Without
* `windowsHide`, console-subsystem children such as git.exe allocate a visible
diff --git a/packages/server/src/http/comment-routes.test.ts b/packages/server/src/http/comment-routes.test.ts
new file mode 100644
index 000000000..a6cdb4fb2
--- /dev/null
+++ b/packages/server/src/http/comment-routes.test.ts
@@ -0,0 +1,47 @@
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, test } from 'vitest';
+import { CommentIndex } from '../comments/comment-index.ts';
+import { CommentService } from '../comments/comment-service.ts';
+import { CommentThreadStore } from '../comments/thread-store.ts';
+import { loggerFactory } from '../logger.ts';
+import { createCommentRoutes } from './comment-routes.ts';
+
+/**
+ * Table-level pins for the comments group's mutating declaration. The wire
+ * cannot pin this: the read half of the DNS-rebinding defense applies the
+ * identical loopback + workspace-Host checks to every `/api/*` request, so an
+ * emptied mutating set changes no composition-suite response — only which
+ * gate (and telemetry tag) fires first. The declared membership is pinned
+ * here directly against the legacy `MUTATING_ROUTES` membership it
+ * reproduces.
+ */
+
+function buildGroup() {
+ const log = loggerFactory.getLogger('test');
+ return createCommentRoutes({
+ // Store directory is created lazily on first write, so a nonexistent
+ // tmp path never touches disk at construction.
+ commentService: new CommentService({
+ store: new CommentThreadStore(join(tmpdir(), 'ok-comment-routes-test-none'), log),
+ index: new CommentIndex(),
+ getDocBody: () => null,
+ getDocFrontmatter: () => null,
+ }),
+ getPrincipal: undefined,
+ signalChannel: undefined,
+ });
+}
+
+describe('createCommentRoutes table', () => {
+ test('registers exactly the two comment paths', () => {
+ expect([...buildGroup().paths].sort()).toEqual(['/api/comment', '/api/comments'].sort());
+ });
+
+ test('both paths are mutating — URL-keyed, GET arms included', () => {
+ const { table } = buildGroup();
+ for (const path of ['/api/comments', '/api/comment']) {
+ expect(table.isMutating(path), path).toBe(true);
+ }
+ });
+});
diff --git a/packages/server/src/http/comment-routes.ts b/packages/server/src/http/comment-routes.ts
new file mode 100644
index 000000000..35776b120
--- /dev/null
+++ b/packages/server/src/http/comment-routes.ts
@@ -0,0 +1,54 @@
+/**
+ * The comments family — `comments` (list/create) and `comment`
+ * (read/mutate/remove) — natively routed as one group. The verb handlers were
+ * already lifted into `comments/comment-api.ts`; this factory owns the
+ * `createCommentApi` wiring and the route table so the extension's legacy
+ * record loses the paths in the same change. The `CommentService` itself stays
+ * in the extension (its store construction is coupled to the rename walk) and
+ * arrives as a dep.
+ *
+ * Both paths are legacy `MUTATING_ROUTES` members, URL-keyed: every verb —
+ * the GET list/read arms included — rides the mutating gate, exactly the
+ * legacy admission. The mutating sub-handlers thread `extractActorIdentity`
+ * inside `comment-api.ts`.
+ */
+
+import type { Principal } from '@inkeep/open-knowledge-core';
+import { createCommentApi } from '../comments/comment-api.ts';
+import type { CommentService } from '../comments/comment-service.ts';
+import { type ApiRouteGroup, type ApiRouteRecord, createApiRouteGroup } from './api-pipeline.ts';
+import { methodRouter } from './method-router.ts';
+
+export interface CommentRouteDeps {
+ commentService: CommentService;
+ getPrincipal: (() => Principal | null) | undefined;
+ /** The extension's CC1 nudge; only the `comments` channel is signalled here. */
+ signalChannel: ((channel: 'files' | 'lint-config' | 'comments') => void) | undefined;
+}
+
+export function createCommentRoutes(deps: CommentRouteDeps): ApiRouteGroup {
+ const { commentService, getPrincipal, signalChannel } = deps;
+
+ const commentApi = createCommentApi({
+ service: commentService,
+ getPrincipal,
+ onChanged: () => signalChannel?.('comments'),
+ });
+ const handleCommentsRoute = methodRouter(
+ { GET: commentApi.list, POST: commentApi.create },
+ { handler: 'comments' },
+ );
+ const handleCommentRoute = methodRouter(
+ { GET: commentApi.read, POST: commentApi.mutate, DELETE: commentApi.remove },
+ { handler: 'comment' },
+ );
+
+ const routes = {
+ '/api/comments': handleCommentsRoute,
+ '/api/comment': handleCommentRoute,
+ } satisfies ApiRouteRecord;
+
+ return createApiRouteGroup(routes, {
+ mutating: ['/api/comments', '/api/comment'],
+ });
+}
diff --git a/packages/server/src/http/file-ops-routes.ts b/packages/server/src/http/file-ops-routes.ts
index 108d6a3ca..ddbeb4f20 100644
--- a/packages/server/src/http/file-ops-routes.ts
+++ b/packages/server/src/http/file-ops-routes.ts
@@ -1308,7 +1308,7 @@ export function createFileOpsRoutes(deps: FileOpsRouteDeps): ApiRouteGroup {
// restoreLifecycleFromConflictsJson disconnects them). Falling back
// to ConflictStore via SyncEngine catches that eviction race —
// mirrors the dual-source pattern used in handleSyncConflictContent's
- // 404 gate.
+ // 404 gate (in `sync-routes.ts`).
// Enumerate from disk (not the lagging file index) so the conflict
// pre-check sees every on-disk child of the folder — same root cause
// as the spine's `affectedDocNames`.
diff --git a/packages/server/src/http/git-routes.test.ts b/packages/server/src/http/git-routes.test.ts
new file mode 100644
index 000000000..3ea024fad
--- /dev/null
+++ b/packages/server/src/http/git-routes.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, test } from 'vitest';
+import type { FileIndexEntry } from '../file-watcher.ts';
+import { createGitRoutes } from './git-routes.ts';
+
+/**
+ * Table-level pins for the git group's mutating declaration. The wire cannot
+ * pin this: the read half of the DNS-rebinding defense applies the identical
+ * loopback + workspace-Host checks to every `/api/*` request, so an emptied
+ * mutating set changes no composition-suite response — only which gate (and
+ * telemetry tag) fires first. The declared membership is pinned here directly
+ * against the legacy `MUTATING_ROUTES` membership it reproduces.
+ */
+
+function buildGroup() {
+ return createGitRoutes({
+ projectDir: undefined,
+ contentDir: '/nonexistent-content',
+ contentFilter: undefined,
+ getFileIndex: () => new Map<string, FileIndexEntry>(),
+ checkLocalOpSecurity: () => true,
+ getSyncEngine: undefined,
+ getPrincipal: undefined,
+ localOpCliArgs: ['open-knowledge'],
+ });
+}
+
+describe('createGitRoutes table', () => {
+ test('registers exactly the three git paths', () => {
+ expect([...buildGroup().paths].sort()).toEqual(
+ ['/api/git/branch-info', '/api/git/worktree-status', '/api/git/checkout'].sort(),
+ );
+ });
+
+ test('checkout is mutating; the two reads are not', () => {
+ const { table } = buildGroup();
+ expect(table.isMutating('/api/git/checkout')).toBe(true);
+ for (const path of ['/api/git/branch-info', '/api/git/worktree-status']) {
+ expect(table.isMutating(path), path).toBe(false);
+ }
+ });
+});
diff --git a/packages/server/src/http/git-routes.ts b/packages/server/src/http/git-routes.ts
new file mode 100644
index 000000000..e31e74b2f
--- /dev/null
+++ b/packages/server/src/http/git-routes.ts
@@ -0,0 +1,298 @@
+/**
+ * The git family — `git/branch-info` and `git/worktree-status` (reads) plus
+ * `git/checkout` (mutating) — natively routed as one group. Handler bodies
+ * move byte-identically from the legacy dispatch; what they closed over in
+ * the extension arrives as {@link GitRouteDeps}. `toOpenTarget` moves with
+ * its sole consumer, the worktree-status handler.
+ *
+ * `git/checkout` keeps its legacy `MUTATING_ROUTES` membership, declared on
+ * the table and pinned in the co-located table-tier test; the two reads stay
+ * on the read posture.
+ */
+
+import { existsSync } from 'node:fs';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { join, relative } from 'node:path';
+import {
+ BranchInfoResponseSchema,
+ CheckoutRequestSchema,
+ CheckoutResponseSchema,
+ EmptyRequestSchema,
+ type GitWorktreeOpenTarget,
+ GitWorktreeStatusSuccessSchema,
+ type Principal,
+} from '@inkeep/open-knowledge-core';
+import type { ContentFilter } from '../content-filter.ts';
+import { stripDocExtension } from '../doc-extensions.ts';
+import { extractActorIdentity } from '../extract-actor-identity.ts';
+import type { FileIndexEntry } from '../file-watcher.ts';
+import {
+ BRANCH_INFO_HANDLER_TAG,
+ computeBranchInfo,
+ isValidBranchInfoPath,
+ isValidBranchName,
+} from '../git-branch-info.ts';
+import { CHECKOUT_HANDLER_TAG, runCheckoutFlow } from '../git-checkout.ts';
+import { buildSyncCredentialConfig, withParentLock } from '../git-handle.ts';
+import { readWorktreeStatus } from '../git-worktree-status.ts';
+import { toPosix } from '../path-utils.ts';
+import { shouldResetAmbientCredentials } from '../share/git-context.ts';
+import type { SyncEngine } from '../sync-engine.ts';
+import { type ApiRouteGroup, type ApiRouteRecord, createApiRouteGroup } from './api-pipeline.ts';
+import { errorResponse } from './error-response.ts';
+import { parseQuery } from './handler-utils.ts';
+import { withValidation } from './request-validation.ts';
+import { successResponse } from './success-response.ts';
+
+export interface GitRouteDeps {
+ projectDir: string | undefined;
+ contentDir: string;
+ contentFilter: ContentFilter | undefined;
+ /** The extension's live doc-name index accessor. */
+ getFileIndex: () => ReadonlyMap<string, FileIndexEntry>;
+ /** The extension's shared local-op security gate (emits RFC 9457 on refusal). */
+ checkLocalOpSecurity: (
+ req: IncomingMessage,
+ res: ServerResponse,
+ opts: { handler: string },
+ ) => boolean;
+ getSyncEngine: (() => SyncEngine | null) | undefined;
+ getPrincipal: (() => Principal | null) | undefined;
+ /** The resolved CLI argv checkout's credential config is built from. */
+ localOpCliArgs: string[];
+}
+
+export function createGitRoutes(deps: GitRouteDeps): ApiRouteGroup {
+ const {
+ projectDir,
+ contentDir,
+ contentFilter,
+ getFileIndex,
+ checkLocalOpSecurity,
+ getSyncEngine,
+ getPrincipal,
+ localOpCliArgs,
+ } = deps;
+
+ /**
+ * Where a project-relative working-tree path opens, or undefined when it
+ * opens nowhere. Resolves to the same two routes the Files sidebar uses, so
+ * a row in the sync popover behaves like the same file in the tree.
+ *
+ * Order is the whole design. File-index membership decides `doc` — the index
+ * holds exactly what the editor owns, so a gitignored `.md` falls through to
+ * the asset viewer rather than opening an editable surface it is not indexed
+ * for. Everything else that survives the filter's FLOORS is an `asset`: the
+ * text-view endpoint has no extension gate, so `.gitignore`, `opencode.json`
+ * and `.ok/config.yml` all render, and the viewer's own fallback pane covers
+ * whatever it cannot draw. `bypassFilters` + `showOk` reduce the filter to
+ * exactly those floors — secret-bearing files, `.git`, `node_modules`,
+ * `.ok/local`, reserved synthetic names — which is the same set the sidebar
+ * refuses to show under Show All Files. Without a content filter there is no
+ * floor to enforce, so nothing is offered.
+ */
+ function toOpenTarget(projectRelPath: string): GitWorktreeOpenTarget | undefined {
+ const absPath = join(projectDir ?? contentDir, projectRelPath);
+ const contentRelPath = toPosix(relative(contentDir, absPath));
+ if (!contentRelPath || contentRelPath.startsWith('..')) return undefined;
+ const docName = stripDocExtension(contentRelPath);
+ if (getFileIndex().has(docName)) return { kind: 'doc', docName };
+ if (!contentFilter) return undefined;
+ if (contentFilter.isExcluded(contentRelPath, { bypassFilters: true, showOk: true })) {
+ return undefined;
+ }
+ // A deletion, or an incoming file that has not landed yet: the viewer would
+ // open on nothing. Docs skip this check — index membership implies the file.
+ if (!existsSync(absPath)) return undefined;
+ return { kind: 'asset', path: contentRelPath };
+ }
+
+ /**
+ * `GET /api/git/worktree-status` — the `git status` view the sync popover
+ * renders under its action buttons.
+ *
+ * Kept off the `sync-status` payload deliberately: that one is pushed over
+ * CC1 on every engine transition, and a working-tree listing does not belong
+ * on a hot broadcast channel. This is polled by the popover while it is open.
+ */
+ async function handleGitWorktreeStatus(req: IncomingMessage, res: ServerResponse): Promise<void> {
+ if (!checkLocalOpSecurity(req, res, { handler: 'git-worktree-status' })) return;
+ if (req.method !== 'GET') {
+ errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {
+ handler: 'git-worktree-status',
+ extraHeaders: { Allow: 'GET' },
+ });
+ return;
+ }
+ try {
+ const engine = getSyncEngine?.();
+ // Without an engine there is no admission predicate to mark scope with.
+ // Report every path as out-of-scope rather than guessing in-scope: an
+ // unmarked path the user then watches Push ignore is the worse failure.
+ const isSyncScoped = engine
+ ? (relPath: string) => engine.isSyncScopedPath(relPath)
+ : () => false;
+ const status = await readWorktreeStatus(projectDir ?? contentDir, isSyncScoped, toOpenTarget);
+ successResponse(res, 200, GitWorktreeStatusSuccessSchema, status, {
+ handler: 'git-worktree-status',
+ });
+ } catch (e) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'git-worktree-status',
+ cause: e,
+ });
+ }
+ }
+
+ /**
+ * `GET /api/git/branch-info?branch=<targetBranch>&path=<path>` — batched
+ * view of git state for the share-receive branch-switch dialog:
+ * - `currentBranch` / `currentHeadSha` / `detached` — HEAD identity
+ * - `shareTargetExists` — `git cat-file -e <ref>:<path>` against the
+ * current ref (HEAD when detached)
+ * - `dirtyConflicts` — `dirtyFilesOverlapWith(projectDir, targetBranch)`
+ * - `branchIsLocal` — `git rev-parse --verify refs/heads/<targetBranch>`
+ *
+ * All four probes run in parallel via `Promise.all` to stay under the
+ * P99 < 500ms NFR. Read-only — does NOT acquire `withParentLock` so
+ * concurrent sync-engine writes don't serialize behind the dialog
+ * probe.
+ */
+ const handleBranchInfo = withValidation(
+ EmptyRequestSchema,
+ async (req, res) => {
+ try {
+ if (!projectDir) {
+ errorResponse(
+ res,
+ 500,
+ 'urn:ok:error:internal-server-error',
+ 'projectDir is not configured for this server.',
+ { handler: BRANCH_INFO_HANDLER_TAG },
+ );
+ return;
+ }
+ const params = parseQuery(req);
+ const branch = params.get('branch');
+ const path = params.get('path');
+ // `kind` defaults to 'doc' when absent — keeps the existing
+ // branch-info callers (which omit it) green until later stories
+ // thread it through the share-receive dialog.
+ const kindParam = params.get('kind');
+ const kind: 'doc' | 'folder' = kindParam === 'folder' ? 'folder' : 'doc';
+ if (!isValidBranchName(branch)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ 'branch query param missing or malformed.',
+ { handler: BRANCH_INFO_HANDLER_TAG },
+ );
+ return;
+ }
+ if (!isValidBranchInfoPath(path, kind)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ 'path query param missing or malformed.',
+ { handler: BRANCH_INFO_HANDLER_TAG },
+ );
+ return;
+ }
+ // The desktop sends the URL-derived repository coordinate explicitly.
+ // V1 has no mount metadata and must never be re-rooted from receiver
+ // config; v2 already projected its separate content target at decode.
+ const info = await computeBranchInfo(projectDir, branch, path, kind);
+ successResponse(res, 200, BranchInfoResponseSchema, info, {
+ handler: BRANCH_INFO_HANDLER_TAG,
+ });
+ } catch (err) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: BRANCH_INFO_HANDLER_TAG,
+ cause: err,
+ });
+ }
+ },
+ {
+ handler: BRANCH_INFO_HANDLER_TAG,
+ method: 'GET',
+ skipBodyParse: true,
+ },
+ );
+
+ /**
+ * `POST /api/git/checkout` — share-receive branch-switch executor.
+ *
+ * Wrapped in `withParentLock` so checkout serializes against the
+ * sync-engine's parent-git writes (precedent: every other parent-git
+ * write goes through this primitive). The branch-info endpoint is
+ * read-only and lock-free; checkout is the matching writer.
+ *
+ * Identity is threaded through `extractActorIdentity` for observability
+ * only — checkout is a git-level operation with no CRDT mutation. The
+ * attribution-sweep meta-test exempts this handler explicitly.
+ *
+ * HEAD watcher is NOT coupled to this endpoint. The 200 response means
+ * `git checkout` completed; the CRDT transition (Y.Docs reset + CC1
+ * `branch-switched` broadcast) runs independently when the HEAD
+ * watcher's `onBatchBegin`/`onBatchEnd` cycle fires.
+ */
+ const handleCheckout = withValidation(
+ CheckoutRequestSchema,
+ async (_req, res, body) => {
+ const bodyObj = body as unknown as Record<string, unknown>;
+ const actor = extractActorIdentity(bodyObj, getPrincipal);
+ if (actor.kind === 'invalid-summary') {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Summary must be a string.', {
+ handler: CHECKOUT_HANDLER_TAG,
+ });
+ return;
+ }
+
+ if (!projectDir) {
+ errorResponse(
+ res,
+ 500,
+ 'urn:ok:error:internal-server-error',
+ 'projectDir is not configured for this server.',
+ { handler: CHECKOUT_HANDLER_TAG },
+ );
+ return;
+ }
+
+ try {
+ const outcome = await withParentLock(() =>
+ runCheckoutFlow(projectDir, body.branch, {
+ fastForward: body.fastForward === true,
+ credentialConfig: buildSyncCredentialConfig(localOpCliArgs, {
+ resetAmbient: shouldResetAmbientCredentials(projectDir),
+ }),
+ }),
+ );
+ successResponse(res, 200, CheckoutResponseSchema, outcome, {
+ handler: CHECKOUT_HANDLER_TAG,
+ });
+ } catch (err) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: CHECKOUT_HANDLER_TAG,
+ cause: err,
+ });
+ }
+ },
+ {
+ handler: CHECKOUT_HANDLER_TAG,
+ method: 'POST',
+ },
+ );
+
+ const routes = {
+ '/api/git/branch-info': handleBranchInfo,
+ '/api/git/worktree-status': handleGitWorktreeStatus,
+ '/api/git/checkout': handleCheckout,
+ } satisfies ApiRouteRecord;
+
+ return createApiRouteGroup(routes, {
+ mutating: ['/api/git/checkout'],
+ });
+}
diff --git a/packages/server/src/http/share-routes.test.ts b/packages/server/src/http/share-routes.test.ts
new file mode 100644
index 000000000..f150ac289
--- /dev/null
+++ b/packages/server/src/http/share-routes.test.ts
@@ -0,0 +1,135 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+import { makeCaptureRes, makeSyntheticReq } from '../composition-rig.test-helper.ts';
+import { loggerFactory } from '../logger.ts';
+import { SHARE_PUBLISH_TIMEOUT_MS } from '../share/publish.ts';
+import { createShareRoutes, type ShareRouteDeps } from './share-routes.ts';
+
+/**
+ * Table-level pins for the share group's (empty) mutating declaration. The
+ * wire cannot pin this: the read half of the DNS-rebinding defense applies
+ * the identical loopback + workspace-Host checks to every `/api/*` request,
+ * so a membership change alters no composition-suite response — only which
+ * gate (and telemetry tag) fires first. `share/publish` staying OFF the
+ * mutating set is deliberate legacy parity (external egress behind the
+ * local-op pre-body gate, not content mutation), and this suite records that
+ * membership as the byte-exact carry-over it is. Hardening `share/publish`
+ * onto the mutating set later is a legitimate, separately-reviewed follow-up
+ * (its Host check is universal today, so the wire outcome is unchanged) — this
+ * pin marks the parity baseline to change deliberately, not a prohibition.
+ */
+
+function buildGroup(overrides: Partial<ShareRouteDeps> = {}) {
+ return createShareRoutes({
+ projectDir: undefined,
+ contentDir: '/nonexistent-content',
+ log: loggerFactory.getLogger('test'),
+ checkLocalOpSecurity: () => true,
+ localOpCliArgs: ['open-knowledge'],
+ localOpGuard: { tryAcquire: () => true, release: () => {} },
+ getSyncEngine: undefined,
+ toGitRelativePath: () => null,
+ ...overrides,
+ });
+}
+
+describe('createShareRoutes table', () => {
+ test('registers exactly the five share paths', () => {
+ expect([...buildGroup().paths].sort()).toEqual(
+ [
+ '/api/share/construct-url',
+ '/api/share/target-status',
+ '/api/share/publish/owners',
+ '/api/share/publish/name-check',
+ '/api/share/publish',
+ ].sort(),
+ );
+ });
+
+ test('no share path is mutating — share/publish included, matching the legacy set', () => {
+ const { table } = buildGroup();
+ for (const path of [
+ '/api/share/construct-url',
+ '/api/share/target-status',
+ '/api/share/publish/owners',
+ '/api/share/publish/name-check',
+ '/api/share/publish',
+ ]) {
+ expect(table.isMutating(path), path).toBe(false);
+ }
+ });
+});
+
+describe('spawnShareSubprocess timeout settlement', () => {
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ // Pins that the timer is a genuine SETTLE branch: a signal-resistant child
+ // that never exits must still land the 500 and release the localOpGuard
+ // slot. The fixture TRAPS SIGTERM — that is the discriminator: the pre-fix
+ // shape's timer only sent SIGTERM and settled on 'close', so against this
+ // child it hangs (the trap swallows the signal, 'close' never fires), while
+ // the settle-at-timer shape rejects on the clock regardless. The `-e`
+ // script ignores the appended share CLI argv. (What this proves: timeout
+ // settlement + slot release against an uncooperative child. It does not
+ // reproduce the harder wedge modes — D-state, grandchild-held stdio.)
+ test('a SIGTERM-trapping, never-exiting subprocess times out to a 500 and releases the guard slot', async () => {
+ // Fake ONLY the pair the handler's kill timer uses. setImmediate stays
+ // real so the readiness wait below can make progress without moving the
+ // faked clock.
+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+ const readyPath = join(tmpdir(), `ok-share-latch-ready-${randomUUID()}`);
+ const acquired: string[] = [];
+ const released: string[] = [];
+ const group = buildGroup({
+ localOpCliArgs: [
+ process.execPath,
+ '-e',
+ // The trap must be INSTALLED before the clock advances, or the signal
+ // hits the still-booting child's default disposition and the child
+ // dies — making even the pre-fix settle-on-'close' shape pass. The
+ // ready-file write after the trap is the barrier the test waits on.
+ `process.on('SIGTERM', () => {}); require('node:fs').writeFileSync(${JSON.stringify(
+ readyPath,
+ )}, 'x'); setInterval(() => {}, 1000);`,
+ ],
+ localOpGuard: {
+ tryAcquire: (key: string) => {
+ acquired.push(key);
+ return true;
+ },
+ release: (key: string) => {
+ released.push(key);
+ },
+ },
+ });
+ try {
+ const resolved = group.table.resolve('/api/share/publish/owners');
+ if (!resolved?.dispatch) throw new Error('no dispatch for /api/share/publish/owners');
+ const req = makeSyntheticReq({ url: '/api/share/publish/owners', method: 'GET' });
+ const { res, captured } = makeCaptureRes();
+ const dispatched = resolved.dispatch(req, res);
+ // Wait (real event loop, no faked clock) until the child has installed
+ // its SIGTERM trap. Doubles as the spawn-succeeded checkpoint: in a
+ // sandbox that refuses exec, 'error' fires instead, the same detail-less
+ // 500 lands WITHOUT the timer branch ever running, and this barrier
+ // never satisfies — the test fails on its own timeout rather than
+ // greenlighting a path that proves nothing about settlement.
+ while (!existsSync(readyPath)) {
+ await new Promise((r) => setImmediate(r));
+ }
+ expect(released).toEqual([]);
+ await vi.advanceTimersByTimeAsync(SHARE_PUBLISH_TIMEOUT_MS + 1);
+ await dispatched;
+ expect(captured.status).toBe(500);
+ expect(acquired).toEqual(['/api/share/publish/owners']);
+ expect(released).toEqual(['/api/share/publish/owners']);
+ } finally {
+ rmSync(readyPath, { force: true });
+ }
+ });
+});
diff --git a/packages/server/src/http/share-routes.ts b/packages/server/src/http/share-routes.ts
new file mode 100644
index 000000000..9ad6cbac3
--- /dev/null
+++ b/packages/server/src/http/share-routes.ts
@@ -0,0 +1,754 @@
+/**
+ * The share family — `share/construct-url`, `share/target-status`, and the
+ * publish trio (`share/publish/owners`, `share/publish/name-check`,
+ * `share/publish`) — natively routed as one group. Handler bodies move
+ * byte-identically from the legacy dispatch; what they closed over in the
+ * extension arrives as {@link ShareRouteDeps}.
+ *
+ * None of these paths was a legacy `MUTATING_ROUTES` member, `share/publish`
+ * included: its admission posture is external egress behind the
+ * `checkLocalOpSecurity` pre-body gate rather than content mutation, and the
+ * lift preserves that membership byte-exactly (pinned in the co-located
+ * table-tier test).
+ */
+
+import { spawn } from 'node:child_process';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import {
+ EmptyRequestSchema,
+ encodeShareUrl,
+ InvalidShareUrlError,
+ parseCanonicalGitHubShareUrl,
+ ShareConstructUrlRequestSchema,
+ ShareConstructUrlResponseSchema,
+ SharePublishNameCheckResponseSchema,
+ SharePublishOwnersResponseSchema,
+ SharePublishRequestSchema,
+ SharePublishResponseSchema,
+ ShareTargetStatusRequestSchema,
+ ShareTargetStatusResponseSchema,
+} from '@inkeep/open-knowledge-core';
+import {
+ LOCAL_OP_PIPE_STDIO_OPTIONS,
+ withHiddenWindowsConsole,
+} from '../child-process-windows-hide.ts';
+import { isValidBranchInfoPath } from '../git-branch-info.ts';
+import { buildSyncCredentialConfig } from '../git-handle.ts';
+import type { ConcurrencyGuard } from '../local-op-security.ts';
+import type { PinoLogger } from '../logger.ts';
+import {
+ buildGitHubBlobUrl,
+ buildGitHubTreeUrl,
+ emitShareConstructUrlLog,
+ isValidSharePath,
+ SHARE_BASE_URL,
+ SHARE_CONSTRUCT_URL_HANDLER_TAG,
+} from '../share/construct-url.ts';
+import { computeShareFreshness } from '../share/freshness.ts';
+import {
+ branchExistsOnOrigin,
+ readGitHeadBranch,
+ readOriginGitHubRepo,
+ shouldResetAmbientCredentials,
+} from '../share/git-context.ts';
+import {
+ emitSharePublishLog,
+ isValidShareOwnerName,
+ isValidShareRepoName,
+ parseNameCheckEvent,
+ parseOwnersEvent,
+ parsePublishEvent,
+ pickTerminalJsonLine,
+ redactShareSubprocessStderr,
+ SHARE_PUBLISH_HANDLER_TAG,
+ SHARE_PUBLISH_KEY,
+ SHARE_PUBLISH_NAME_CHECK_HANDLER_TAG,
+ SHARE_PUBLISH_NAME_CHECK_KEY,
+ SHARE_PUBLISH_OWNERS_HANDLER_TAG,
+ SHARE_PUBLISH_OWNERS_KEY,
+ SHARE_PUBLISH_TIMEOUT_MS,
+} from '../share/publish.ts';
+import {
+ computeShareTargetStatus,
+ SHARE_TARGET_STATUS_HANDLER_TAG,
+} from '../share/target-status.ts';
+import type { SyncEngine } from '../sync-engine.ts';
+import { type ApiRouteGroup, type ApiRouteRecord, createApiRouteGroup } from './api-pipeline.ts';
+import { errorResponse } from './error-response.ts';
+import { parseQuery } from './handler-utils.ts';
+import { withValidation } from './request-validation.ts';
+import { successResponse } from './success-response.ts';
+
+export interface ShareRouteDeps {
+ projectDir: string | undefined;
+ contentDir: string;
+ log: PinoLogger;
+ /** The extension's shared local-op security gate (emits RFC 9457 on refusal). */
+ checkLocalOpSecurity: (
+ req: IncomingMessage,
+ res: ServerResponse,
+ opts: { handler: string },
+ ) => boolean;
+ /** The resolved CLI argv the extension spawns share subcommands with. */
+ localOpCliArgs: string[];
+ /** The extension's per-endpoint concurrency guard — one slot per publish key. */
+ localOpGuard: ConcurrencyGuard;
+ getSyncEngine: (() => SyncEngine | null) | undefined;
+ /**
+ * Repo-root-relative projection for an absolute path, or null when the path
+ * escapes the project — stays in the extension (shared with the rename
+ * spine) and arrives by reference.
+ */
+ toGitRelativePath: (projectDir: string, absolutePath: string) => string | null;
+}
+
+export function createShareRoutes(deps: ShareRouteDeps): ApiRouteGroup {
+ const {
+ projectDir,
+ contentDir,
+ log,
+ checkLocalOpSecurity,
+ localOpCliArgs,
+ localOpGuard,
+ getSyncEngine,
+ toGitRelativePath,
+ } = deps;
+
+ /**
+ * `POST /api/share/construct-url` — read the project's local git state and
+ * emit a marketing-safe share URL (`https://openknowledge.ai/d/<base64url>`)
+ * pinned to HEAD branch + the focused doc. Read-only against the working
+ * tree: no commits, no pushes, no fetches, no `git ls-remote`.
+ * Branch-existence is checked locally against `refs/remotes/origin/<branch>`;
+ * the false-negative window (last fetch ran before the push) is acceptable;
+ * the toast prompts the user to
+ * push, the retry succeeds.
+ *
+ * Returns HTTP 200 with `{ok: false, error: code}` for the six business-
+ * logic failures (no-remote, detached-head, branch-not-on-origin,
+ * non-github-remote, invalid-path, unsupported-share-url) — DELIBERATE
+ * departure from RFC 9457 for these branches. The Share UI maps each code to a per-toast string;
+ * routing through 4xx would conflate share-flow outcomes with transport
+ * errors the client retries differently. Transport-class failures
+ * (loopback gate, payload-too-large, body-parse) still emit RFC 9457 via
+ * `errorResponse`.
+ */
+ const handleShareConstructUrl = withValidation(
+ ShareConstructUrlRequestSchema,
+ async (_req, res, body) => {
+ try {
+ if (!projectDir) {
+ emitShareConstructUrlLog('no-remote', { kind: body.kind });
+ successResponse(
+ res,
+ 200,
+ ShareConstructUrlResponseSchema,
+ { ok: false, error: 'no-remote' },
+ { handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
+ );
+ return;
+ }
+ // Path validation is kind-specific: doc paths always name a file
+ // (non-empty); folder paths may target the content root (empty).
+ const sharePath = body.kind === 'doc' ? body.docPath : body.folderPath;
+ if (!isValidSharePath(sharePath, body.kind)) {
+ emitShareConstructUrlLog('invalid-path', { kind: body.kind });
+ successResponse(
+ res,
+ 200,
+ ShareConstructUrlResponseSchema,
+ { ok: false, error: 'invalid-path' },
+ { handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
+ );
+ return;
+ }
+ const branch = readGitHeadBranch(projectDir);
+ if (branch === null) {
+ // Two upstream causes ride this branch: (a) detached HEAD — the
+ // sender must check out a branch; (b) no `.git/HEAD` at all (not a
+ // git repo) — also caught downstream by `readOriginGitHubRepo`
+ // returning `no-remote`. Disambiguate via the origin lookup so the
+ // toast says the right thing.
+ const originPeek = readOriginGitHubRepo(projectDir);
+ if (originPeek.kind === 'no-remote') {
+ emitShareConstructUrlLog('no-remote', { kind: body.kind });
+ successResponse(
+ res,
+ 200,
+ ShareConstructUrlResponseSchema,
+ { ok: false, error: 'no-remote' },
+ { handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
+ );
+ return;
+ }
+ emitShareConstructUrlLog('detached-head', { kind: body.kind });
+ successResponse(
+ res,
+ 200,
+ ShareConstructUrlResponseSchema,
+ { ok: false, error: 'detached-head' },
+ { handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
+ );
+ return;
+ }
+ const origin = readOriginGitHubRepo(projectDir);
+ if (origin.kind === 'no-remote') {
+ emitShareConstructUrlLog('no-remote', { kind: body.kind });
+ successResponse(
+ res,
+ 200,
+ ShareConstructUrlResponseSchema,
+ { ok: false, error: 'no-remote' },
+ { handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
+ );
+ return;
+ }
+ // Known non-GitHub forges (gitlab, bitbucket) can't produce a GitHub
+ // share URL. GitHub hosts — github.com AND GHES — are supported: the
+ // builders below take `origin.host` and the receive side accepts the
+ // enterprise host behind its trust gate.
+ if (origin.kind === 'non-github') {
+ emitShareConstructUrlLog('non-github-remote', { kind: body.kind });
+ successResponse(
+ res,
+ 200,
+ ShareConstructUrlResponseSchema,
+ { ok: false, error: 'non-github-remote' },
+ { handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
+ );
+ return;
+ }
+ const branchExists = branchExistsOnOrigin(projectDir, branch);
+ if (!branchExists) {
+ emitShareConstructUrlLog('branch-not-on-origin', {
+ branchExists: false,
+ kind: body.kind,
+ });
+ successResponse(
+ res,
+ 200,
+ ShareConstructUrlResponseSchema,
+ { ok: false, error: 'branch-not-on-origin', branch },
+ { handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
+ );
+ return;
+ }
+ // content.dir relative to the repo root. `''` when `content.dir === '.'`
+ // (the dominant case). `null` (distinct from `''`) means contentDir
+ // escapes projectDir — a project misconfiguration that breaks the
+ // content-root invariant; fail loud via the outer catch (→ 500) rather
+ // than collapsing to `''`, which would silently mint a share link
+ // pointing at the repo root instead of the (broken) content dir.
+ const contentRel = toGitRelativePath(projectDir, contentDir);
+ if (contentRel === null) {
+ throw new Error('content dir is not contained within the project dir');
+ }
+ const repositorySharePath =
+ contentRel === ''
+ ? sharePath
+ : sharePath === ''
+ ? contentRel
+ : `${contentRel}/${sharePath}`;
+ let sharedUrl: string;
+ if (body.kind === 'doc') {
+ sharedUrl = buildGitHubBlobUrl(
+ origin.host,
+ origin.owner,
+ origin.repo,
+ branch,
+ repositorySharePath,
+ );
+ } else {
+ sharedUrl = buildGitHubTreeUrl(
+ origin.host,
+ origin.owner,
+ origin.repo,
+ branch,
+ repositorySharePath,
+ );
+ }
+ // Derive depth through the same canonical build + parse contract the
+ // reader uses. For valid contentRel values this count equals a raw
+ // slash split; the round-trip also validates the encoded URL before
+ // minting the token.
+ let shareUrl: string;
+ try {
+ const contentRootDepth =
+ contentRel === ''
+ ? 0
+ : parseCanonicalGitHubShareUrl(
+ buildGitHubTreeUrl(origin.host, origin.owner, origin.repo, branch, contentRel),
+ ).targetSegments.length;
+ shareUrl = `${SHARE_BASE_URL}${encodeShareUrl(sharedUrl, contentRootDepth)}`;
+ } catch (err) {
+ if (!(err instanceof InvalidShareUrlError)) throw err;
+ emitShareConstructUrlLog('unsupported-share-url', { kind: body.kind });
+ successResponse(
+ res,
+ 200,
+ ShareConstructUrlResponseSchema,
+ { ok: false, error: 'unsupported-share-url' },
+ { handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
+ );
+ return;
+ }
+ const freshness = await computeShareFreshness(
+ projectDir,
+ branch,
+ repositorySharePath,
+ body.kind,
+ );
+ emitShareConstructUrlLog('ok', { branchExists: true, kind: body.kind, freshness });
+ successResponse(
+ res,
+ 200,
+ ShareConstructUrlResponseSchema,
+ { ok: true, shareUrl, sharedUrl, branch, freshness },
+ { handler: SHARE_CONSTRUCT_URL_HANDLER_TAG },
+ );
+ } catch (err) {
+ // Defensive: a future dependency change might add a throwing branch,
+ // and the structured 200 contract above would otherwise leak the throw as an
+ // unhandled-rejection 500. Generic title — raw `err.message` could
+ // include FS paths.
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: SHARE_CONSTRUCT_URL_HANDLER_TAG,
+ cause: err,
+ });
+ }
+ },
+ {
+ handler: SHARE_CONSTRUCT_URL_HANDLER_TAG,
+ method: 'POST',
+ preBodyGate: (req, res) =>
+ checkLocalOpSecurity(req, res, { handler: SHARE_CONSTRUCT_URL_HANDLER_TAG }),
+ },
+ );
+
+ /**
+ * `POST /api/share/target-status` — receive-side verdict for a share link
+ * whose target is missing on the receiver's current ref. Runs a targeted
+ * `git fetch origin <branch>` (authenticated by the user's ambient git
+ * credential helper, same as checkout's fetch; no explicit token injection)
+ * bounded by a timeout, then classifies the miss from git's rename detection:
+ * on-origin (the local ref was stale) / renamed (+ a new path verified to
+ * resolve at the origin ref) / deleted / never-on-branch / unknown (fetch
+ * failed). Fail-open: any error returns `unknown`, and the caller falls back
+ * to today's guidance.
+ *
+ * Updates only remote-tracking refs, no CRDT mutation — so the
+ * attribution-sweep meta-test exempts it (see EXEMPT_HANDLERS).
+ */
+ function projectRenamedShareTarget(
+ repositoryPath: string,
+ renamedRepositoryPath: string,
+ contentRootDepth: number,
+ ): { verdict: 'renamed'; renamedTo: string } | { verdict: 'unknown' } {
+ const originalSegments = repositoryPath.split('/');
+ const renamedSegments = renamedRepositoryPath.split('/');
+ if (contentRootDepth >= originalSegments.length || contentRootDepth >= renamedSegments.length) {
+ return { verdict: 'unknown' };
+ }
+ for (let index = 0; index < contentRootDepth; index += 1) {
+ if (originalSegments[index] !== renamedSegments[index]) return { verdict: 'unknown' };
+ }
+ return { verdict: 'renamed', renamedTo: renamedSegments.slice(contentRootDepth).join('/') };
+ }
+
+ const handleShareTargetStatus = withValidation(
+ ShareTargetStatusRequestSchema,
+ async (_req, res, body) => {
+ try {
+ if (!projectDir) {
+ errorResponse(
+ res,
+ 500,
+ 'urn:ok:error:internal-server-error',
+ 'projectDir is not configured for this server.',
+ { handler: SHARE_TARGET_STATUS_HANDLER_TAG },
+ );
+ return;
+ }
+ // Validate the path shape before it reaches git's `<ref>:<path>`
+ // ref-spec, mirroring the sibling share handlers (construct-url's
+ // `isValidSharePath`, branch-info's `isValidBranchInfoPath`) —
+ // precedent #55 content-scope predicate symmetry. Kind-aware: an empty
+ // path is the folder-root sentinel, invalid for a doc; `..`, `.git`,
+ // control chars, and backslashes are rejected so a malformed path can't
+ // reach git and degrade the verdict classification.
+ if (!isValidBranchInfoPath(body.path, body.kind)) {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'path is missing or malformed.', {
+ handler: SHARE_TARGET_STATUS_HANDLER_TAG,
+ });
+ return;
+ }
+ const status = await computeShareTargetStatus(
+ projectDir,
+ body.branch,
+ body.path,
+ body.kind,
+ {
+ credentialConfig: buildSyncCredentialConfig(localOpCliArgs, {
+ resetAmbient: shouldResetAmbientCredentials(projectDir),
+ }),
+ },
+ );
+ const contentStatus =
+ status.verdict !== 'renamed' || body.contentRootDepth === undefined
+ ? status
+ : projectRenamedShareTarget(body.path, status.renamedTo, body.contentRootDepth);
+ successResponse(res, 200, ShareTargetStatusResponseSchema, contentStatus, {
+ handler: SHARE_TARGET_STATUS_HANDLER_TAG,
+ });
+ } catch (err) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: SHARE_TARGET_STATUS_HANDLER_TAG,
+ cause: err,
+ });
+ }
+ },
+ {
+ handler: SHARE_TARGET_STATUS_HANDLER_TAG,
+ method: 'POST',
+ preBodyGate: (req, res) =>
+ checkLocalOpSecurity(req, res, { handler: SHARE_TARGET_STATUS_HANDLER_TAG }),
+ },
+ );
+
+ /**
+ * Spawn the share-flow CLI subcommand once, with a bounded timeout, and
+ * collect its stdout. Returns the captured text + exit code. Used by all
+ * three publish handlers; the shape mirrors `handleLocalOpAuthStatus`'s
+ * inline spawn so the route-shape meta-tests scan one consistent pattern.
+ *
+ * stderr is piped + collected; on non-zero exit, a redacted prefix is
+ * logged via the `api` logger (`[share] subprocess ...`) so production
+ * failures (git binary missing, keychain denied, Octokit auth error)
+ * leave a diagnostic trail. Credential URLs of the form
+ * `x-access-token:<token>@github.com` get the token replaced with `***`
+ * before logging — the CLI uses inline-token push URLs and a partial git
+ * error could otherwise leak the PAT.
+ *
+ * Throws on spawn-failure / timeout — the handlers map to `errorResponse`.
+ */
+ async function spawnShareSubprocess(
+ args: readonly string[],
+ ): Promise<{ stdout: string; code: number | null }> {
+ const [cmd, ...baseArgs] = localOpCliArgs;
+ const spawnArgs = [...baseArgs, ...args];
+ return await new Promise<{ stdout: string; code: number | null }>((resolveSpawn, reject) => {
+ const child = spawn(
+ cmd,
+ spawnArgs,
+ withHiddenWindowsConsole({
+ ...LOCAL_OP_PIPE_STDIO_OPTIONS,
+ env: { ...process.env },
+ }),
+ );
+ // Settle AT the timer, not at 'close' — the package-wide timeout-kill
+ // shape (illustrative precedents: `rename-log.ts`, `acp/archive.ts`,
+ // `acp/login-shell-path.ts`; the auth-status/signout/repos spawns in
+ // `api-extension.ts` carry the same latch).
+ // Settlement must not depend on the child cooperating: 'close' fires only
+ // after every shared stdio stream ends (a grandchild holding the pipe
+ // write-ends delays it past 'exit'), SIGKILL cannot reap a process in
+ // uninterruptible sleep (stalled network mount), and `child.kill()`
+ // signals one PID, not the tree. So the timer rejects immediately —
+ // freeing the caller's `finally { localOpGuard.release() }` slot — and
+ // the SIGKILL is fire-and-forget process hygiene, not a precondition.
+ let settled = false;
+ const killTimer = setTimeout(() => {
+ if (settled) return;
+ settled = true;
+ try {
+ child.kill('SIGKILL');
+ } catch {
+ // child may already be dead
+ }
+ // Tear the pipes down at settle: a D-state child (or a grandchild
+ // holding the write-ends) can keep streaming into the chunk buffers
+ // after the request has already 500'd — destroy bounds that memory.
+ child.stdout.destroy();
+ child.stderr.destroy();
+ reject(new Error(`share subprocess timed out after ${SHARE_PUBLISH_TIMEOUT_MS}ms`));
+ }, SHARE_PUBLISH_TIMEOUT_MS);
+ killTimer.unref?.();
+ const stdoutChunks: Buffer[] = [];
+ const stderrChunks: Buffer[] = [];
+ child.stdout.on('data', (chunk: Buffer) => stdoutChunks.push(chunk));
+ child.stderr.on('data', (chunk: Buffer) => stderrChunks.push(chunk));
+ child.on('close', (code) => {
+ if (settled) return;
+ settled = true;
+ clearTimeout(killTimer);
+ const stdout = Buffer.concat(stdoutChunks).toString('utf-8');
+ if (code !== 0) {
+ const stderr = Buffer.concat(stderrChunks).toString('utf-8');
+ const redacted = redactShareSubprocessStderr(stderr).slice(0, 500);
+ log.warn(
+ { code, stderr: redacted },
+ `[share] subprocess exited code=${code} stderr=${redacted}`,
+ );
+ }
+ resolveSpawn({ stdout, code });
+ });
+ child.on('error', (err) => {
+ if (settled) return;
+ settled = true;
+ clearTimeout(killTimer);
+ reject(err);
+ });
+ });
+ }
+
+ /**
+ * GET /api/share/publish/owners — list GitHub owners the user can host a
+ * new repo under (owner eligibility). Spawns `open-knowledge share owners --json` and
+ * returns one of:
+ * { ok: true, owners: [...] }
+ * { ok: false, error: 'auth-required' | 'network' }
+ *
+ * The owners endpoint is read-only and idempotent. Its localOpGuard slot is
+ * keyed per endpoint (`SHARE_PUBLISH_OWNERS_KEY`), so it serializes only
+ * concurrent owner-list calls against each other — it does NOT mutually
+ * exclude owner-list from name-check or publish-create, each of which holds
+ * its own distinct key.
+ */
+ const handleSharePublishOwners = withValidation(
+ EmptyRequestSchema,
+ async (_req, res) => {
+ if (!localOpGuard.tryAcquire(SHARE_PUBLISH_OWNERS_KEY)) {
+ errorResponse(
+ res,
+ 429,
+ 'urn:ok:error:concurrent-operation',
+ 'A share owners operation is already in progress.',
+ { handler: SHARE_PUBLISH_OWNERS_HANDLER_TAG, extraHeaders: { 'Retry-After': '5' } },
+ );
+ return;
+ }
+ try {
+ const { stdout } = await spawnShareSubprocess(['share', 'owners', '--json']);
+ const event = pickTerminalJsonLine(stdout);
+ const body = parseOwnersEvent(event);
+ emitSharePublishLog(
+ 'owners-list',
+ body.ok ? 'ok' : body.error,
+ body.ok ? { count: body.owners.length } : undefined,
+ );
+ successResponse(res, 200, SharePublishOwnersResponseSchema, body, {
+ handler: SHARE_PUBLISH_OWNERS_HANDLER_TAG,
+ });
+ } catch (err) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: SHARE_PUBLISH_OWNERS_HANDLER_TAG,
+ cause: err,
+ });
+ } finally {
+ localOpGuard.release(SHARE_PUBLISH_OWNERS_KEY);
+ }
+ },
+ {
+ handler: SHARE_PUBLISH_OWNERS_HANDLER_TAG,
+ method: 'GET',
+ skipBodyParse: true,
+ preBodyGate: (req, res) =>
+ checkLocalOpSecurity(req, res, { handler: SHARE_PUBLISH_OWNERS_HANDLER_TAG }),
+ },
+ );
+
+ /**
+ * GET /api/share/publish/name-check?owner=<o>&name=<n> — pre-flight a repo
+ * name for conflict. Spawns `open-knowledge share name-check --json
+ * --owner X --name Y` and returns one of:
+ * { ok: true, available: boolean }
+ * { ok: false, error: 'auth-required' | 'network' }
+ *
+ * Query-param validation runs server-side: missing/invalid `owner` or
+ * `name` short-circuits to 400 invalid-request BEFORE the subprocess
+ * spawns. This keeps a malformed wizard call from triggering a CLI
+ * exec on every keypress.
+ */
+ const handleSharePublishNameCheck = withValidation(
+ EmptyRequestSchema,
+ async (req, res) => {
+ const params = parseQuery(req);
+ const owner = params.get('owner') ?? '';
+ const name = params.get('name') ?? '';
+ if (!isValidShareOwnerName(owner) || !isValidShareRepoName(name)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ 'owner and name query params must be valid GitHub identifiers.',
+ { handler: SHARE_PUBLISH_NAME_CHECK_HANDLER_TAG },
+ );
+ return;
+ }
+ if (!localOpGuard.tryAcquire(SHARE_PUBLISH_NAME_CHECK_KEY)) {
+ errorResponse(
+ res,
+ 429,
+ 'urn:ok:error:concurrent-operation',
+ 'A share name-check operation is already in progress.',
+ { handler: SHARE_PUBLISH_NAME_CHECK_HANDLER_TAG, extraHeaders: { 'Retry-After': '5' } },
+ );
+ return;
+ }
+ try {
+ const { stdout } = await spawnShareSubprocess([
+ 'share',
+ 'name-check',
+ '--owner',
+ owner,
+ '--name',
+ name,
+ '--json',
+ ]);
+ const event = pickTerminalJsonLine(stdout);
+ const body = parseNameCheckEvent(event);
+ emitSharePublishLog(
+ 'name-check',
+ body.ok ? 'ok' : body.error,
+ body.ok ? { available: body.available } : undefined,
+ );
+ successResponse(res, 200, SharePublishNameCheckResponseSchema, body, {
+ handler: SHARE_PUBLISH_NAME_CHECK_HANDLER_TAG,
+ });
+ } catch (err) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: SHARE_PUBLISH_NAME_CHECK_HANDLER_TAG,
+ cause: err,
+ });
+ } finally {
+ localOpGuard.release(SHARE_PUBLISH_NAME_CHECK_KEY);
+ }
+ },
+ {
+ handler: SHARE_PUBLISH_NAME_CHECK_HANDLER_TAG,
+ method: 'GET',
+ skipBodyParse: true,
+ preBodyGate: (req, res) =>
+ checkLocalOpSecurity(req, res, { handler: SHARE_PUBLISH_NAME_CHECK_HANDLER_TAG }),
+ },
+ );
+
+ /**
+ * POST /api/share/publish — drive a no-remote project to first share (publish flow).
+ * Spawns `open-knowledge share publish --json --owner ... --name ...
+ * --visibility ... [--description ...] --project-dir <projectDir>` and
+ * returns one of:
+ * { ok: true, ownerLogin, repoName, cloneUrl, defaultBranch }
+ * { ok: false, error: <SharePublishErrorCode> }
+ *
+ * `projectDir` is sourced from the server's own `ApiExtensionOptions` —
+ * never trusted from the client — so a hostile caller can't redirect
+ * the publish flow at another project on disk. Absent `projectDir`
+ * surfaces as `no-project` (the editor's wizard knows what to do).
+ */
+ const handleSharePublish = withValidation(
+ SharePublishRequestSchema,
+ async (_req, res, body) => {
+ if (!projectDir) {
+ emitSharePublishLog('publish-create', 'no-project');
+ successResponse(
+ res,
+ 200,
+ SharePublishResponseSchema,
+ { ok: false, error: 'no-project' },
+ { handler: SHARE_PUBLISH_HANDLER_TAG },
+ );
+ return;
+ }
+ if (!isValidShareOwnerName(body.owner) || !isValidShareRepoName(body.name)) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ 'owner and name must be valid GitHub identifiers.',
+ { handler: SHARE_PUBLISH_HANDLER_TAG },
+ );
+ return;
+ }
+ if (!localOpGuard.tryAcquire(SHARE_PUBLISH_KEY)) {
+ errorResponse(
+ res,
+ 429,
+ 'urn:ok:error:concurrent-operation',
+ 'A share publish operation is already in progress.',
+ { handler: SHARE_PUBLISH_HANDLER_TAG, extraHeaders: { 'Retry-After': '5' } },
+ );
+ return;
+ }
+ try {
+ const args = [
+ 'share',
+ 'publish',
+ '--owner',
+ body.owner,
+ '--name',
+ body.name,
+ '--visibility',
+ body.visibility,
+ '--project-dir',
+ projectDir,
+ '--json',
+ ];
+ if (body.description !== undefined && body.description.length > 0) {
+ args.push('--description', body.description);
+ }
+ const { stdout } = await spawnShareSubprocess(args);
+ const event = pickTerminalJsonLine(stdout);
+ const responseBody = parsePublishEvent(event);
+ emitSharePublishLog('publish-create', responseBody.ok ? 'ok' : responseBody.error);
+ if (responseBody.ok) {
+ // A successful publish just added `origin` to the local repo (the
+ // CLI's runPublishFlow addRemote step). The sync engine snapshotted
+ // `hasRemote: false` at boot, so without a nudge the client keeps
+ // routing the Share button into THIS wizard — and the republish
+ // 422s on the repo that now exists. Fire-and-forget re-detection
+ // flips `hasRemote` and signals CC1 'sync-status' so the next Share
+ // click constructs the URL directly. Mirrors the set-identity
+ // handler's refreshIdentity nudge.
+ void getSyncEngine?.()
+ ?.refreshRemote()
+ .catch((err) => {
+ // Best-effort — status catches up on next poll / restart — but a
+ // SYSTEMATIC failure here (broken git config, `.git` perms) leaves
+ // the Share button stuck reopening the first-publish wizard with
+ // nothing in the logs to explain it, so record the rejection.
+ log.warn({ err }, '[share] post-publish refreshRemote failed');
+ });
+ }
+ successResponse(res, 200, SharePublishResponseSchema, responseBody, {
+ handler: SHARE_PUBLISH_HANDLER_TAG,
+ });
+ } catch (err) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: SHARE_PUBLISH_HANDLER_TAG,
+ cause: err,
+ });
+ } finally {
+ localOpGuard.release(SHARE_PUBLISH_KEY);
+ }
+ },
+ {
+ handler: SHARE_PUBLISH_HANDLER_TAG,
+ method: 'POST',
+ preBodyGate: (req, res) =>
+ checkLocalOpSecurity(req, res, { handler: SHARE_PUBLISH_HANDLER_TAG }),
+ },
+ );
+
+ const routes = {
+ '/api/share/construct-url': handleShareConstructUrl,
+ '/api/share/target-status': handleShareTargetStatus,
+ '/api/share/publish/owners': handleSharePublishOwners,
+ '/api/share/publish/name-check': handleSharePublishNameCheck,
+ '/api/share/publish': handleSharePublish,
+ } satisfies ApiRouteRecord;
+
+ // No mutating declaration — byte-exact legacy membership: no share path
+ // rode `MUTATING_ROUTES` (see the module docblock).
+ return createApiRouteGroup(routes);
+}
diff --git a/packages/server/src/http/sync-routes.test.ts b/packages/server/src/http/sync-routes.test.ts
new file mode 100644
index 000000000..4a66209d8
--- /dev/null
+++ b/packages/server/src/http/sync-routes.test.ts
@@ -0,0 +1,124 @@
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Hocuspocus } from '@hocuspocus/server';
+import { describe, expect, test } from 'vitest';
+import { makeCaptureRes, makeSyntheticReq } from '../composition-rig.test-helper.ts';
+import { loggerFactory } from '../logger.ts';
+import type { SyncEngine } from '../sync-engine.ts';
+import { createSyncRoutes } from './sync-routes.ts';
+
+/**
+ * Table-level pins for the sync group's mutating declaration. The wire cannot
+ * pin this: the read half of the DNS-rebinding defense applies the identical
+ * loopback + workspace-Host checks to every `/api/*` request, so an emptied
+ * mutating set changes no composition-suite response — only which gate (and
+ * telemetry tag) fires first. The declared membership is pinned here directly
+ * against the legacy `MUTATING_ROUTES` membership it reproduces.
+ *
+ * Also pinned here (handler tier, synthetic dispatch): conflict-content's
+ * working-tree `ours`-read errno discrimination — only a genuine ENOENT may
+ * classify as the delete overlay; any other read failure must surface as a
+ * 500, never as a silent `delete-modify` the UI resolves with `git rm`.
+ */
+
+function buildGroup() {
+ return createSyncRoutes({
+ projectDir: undefined,
+ hocuspocus: new Hocuspocus({ quiet: true }),
+ log: loggerFactory.getLogger('test'),
+ checkLocalOpSecurity: () => true,
+ getSyncEngine: undefined,
+ serializeDoc: undefined,
+ });
+}
+
+describe('createSyncRoutes table', () => {
+ test('registers exactly the six sync paths', () => {
+ expect([...buildGroup().paths].sort()).toEqual(
+ [
+ '/api/sync/status',
+ '/api/sync/trigger',
+ '/api/sync/conflicts',
+ '/api/sync/conflict-content',
+ '/api/sync/resolve-conflict',
+ '/api/sync/resolve-blocking',
+ ].sort(),
+ );
+ });
+
+ test('the trigger/resolve trio is mutating; the three reads are not', () => {
+ const { table } = buildGroup();
+ for (const path of [
+ '/api/sync/trigger',
+ '/api/sync/resolve-conflict',
+ '/api/sync/resolve-blocking',
+ ]) {
+ expect(table.isMutating(path), path).toBe(true);
+ }
+ for (const path of ['/api/sync/status', '/api/sync/conflicts', '/api/sync/conflict-content']) {
+ expect(table.isMutating(path), path).toBe(false);
+ }
+ });
+});
+
+describe('conflict-content working-tree ours-read errno discrimination', () => {
+ // A working-tree-variant conflict with no pinned shas: `readBlob`
+ // short-circuits on the undefined shas, so the handler reaches the
+ // `ours` disk read without any git subprocess.
+ function buildConflictGroup(projectDir: string) {
+ const engine = {
+ getConflicts: () => [
+ { file: 'a.md', variant: 'working-tree', theirsSha: undefined, baseSha: undefined },
+ ],
+ } as unknown as SyncEngine;
+ return createSyncRoutes({
+ projectDir,
+ hocuspocus: new Hocuspocus({ quiet: true }),
+ log: loggerFactory.getLogger('test'),
+ checkLocalOpSecurity: () => true,
+ getSyncEngine: () => engine,
+ serializeDoc: undefined,
+ });
+ }
+
+ async function dispatchConflictContent(
+ projectDir: string,
+ ): Promise<{ status: number; body: string }> {
+ const resolved = buildConflictGroup(projectDir).table.resolve('/api/sync/conflict-content');
+ if (!resolved?.dispatch) throw new Error('no dispatch for /api/sync/conflict-content');
+ const req = makeSyntheticReq({ url: '/api/sync/conflict-content?file=a.md' });
+ const { res, captured } = makeCaptureRes();
+ await resolved.dispatch(req, res);
+ return captured;
+ }
+
+ test('a genuinely absent working-tree file is the delete overlay (200 delete-modify)', async () => {
+ const projectDir = mkdtempSync(join(tmpdir(), 'sync-cc-enoent-'));
+ try {
+ const captured = await dispatchConflictContent(projectDir);
+ expect(captured.status).toBe(200);
+ expect((JSON.parse(captured.body) as { kind?: string }).kind).toBe('delete-modify');
+ } finally {
+ rmSync(projectDir, { recursive: true, force: true });
+ }
+ });
+
+ test('a non-ENOENT ours-read failure is a 500, never a silent delete-modify', async () => {
+ const projectDir = mkdtempSync(join(tmpdir(), 'sync-cc-eisdir-'));
+ try {
+ // A DIRECTORY at the conflicted path makes readFileSync throw EISDIR —
+ // a portable stand-in for EACCES/EIO (no chmod/root dependency). Before
+ // the errno discrimination this was swallowed into `oursPresent = false`
+ // → 200 `delete-modify` → the UI offers `git rm` on the user's own doc.
+ mkdirSync(join(projectDir, 'a.md'));
+ const captured = await dispatchConflictContent(projectDir);
+ expect(captured.status).toBe(500);
+ expect((JSON.parse(captured.body) as { type?: string }).type).toBe(
+ 'urn:ok:error:internal-server-error',
+ );
+ } finally {
+ rmSync(projectDir, { recursive: true, force: true });
+ }
+ });
+});
diff --git a/packages/server/src/http/sync-routes.ts b/packages/server/src/http/sync-routes.ts
new file mode 100644
index 000000000..e02cfdfb2
--- /dev/null
+++ b/packages/server/src/http/sync-routes.ts
@@ -0,0 +1,706 @@
+/**
+ * The sync family — `sync/status`, `sync/conflicts`, `sync/conflict-content`
+ * (reads) plus `sync/trigger`, `sync/resolve-conflict`, `sync/resolve-blocking`
+ * (mutating) — natively routed as one group. Handler bodies move byte-identically
+ * from the legacy dispatch; what they closed over in the extension arrives as
+ * {@link SyncRouteDeps}. Every endpoint reuses the shared loopback + origin
+ * check from `local-op-security.ts` via the extension's `checkLocalOpSecurity`
+ * shadow, lifted as a dep so the refusal travels with the handlers.
+ *
+ * The mutating trio keeps its legacy `MUTATING_ROUTES` membership, declared on
+ * the table and pinned in the co-located table-tier test.
+ */
+
+import { readFileSync } from 'node:fs';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { join } from 'node:path';
+import type { Hocuspocus } from '@hocuspocus/server';
+import {
+ SyncConflictContentSuccessSchema,
+ SyncConflictsSuccessSchema,
+ SyncResolveBlockingRequestSchema,
+ SyncResolveBlockingSuccessSchema,
+ SyncResolveConflictRequestSchema,
+ SyncResolveConflictSuccessSchema,
+ SyncStatusSchema,
+ SyncTriggerRequestSchema,
+ SyncTriggerSuccessSchema,
+} from '@inkeep/open-knowledge-core';
+import simpleGit from 'simple-git';
+import type { ResolveStrategy } from '../conflict-storage.ts';
+import { isShareableOkArtifact } from '../content-filter.ts';
+import { stripDocExtension } from '../doc-extensions.ts';
+import type { PinoLogger } from '../logger.ts';
+import { assertRealpathWithinDir } from '../symlink-guard.ts';
+import type { SyncEngine } from '../sync-engine.ts';
+import { type ApiRouteGroup, type ApiRouteRecord, createApiRouteGroup } from './api-pipeline.ts';
+import { errorResponse } from './error-response.ts';
+import { errnoCode } from './handler-utils.ts';
+import { withValidation } from './request-validation.ts';
+import { successResponse } from './success-response.ts';
+
+/**
+ * Detects git merge-conflict marker triples at start-of-line. Requires
+ * ALL THREE sentinels (`<<<<<<< `, `=======`, `>>>>>>> `) to co-occur —
+ * git always writes the trio together, so single-sentinel matching would
+ * false-positive on legitimate user content (e.g., a CommonMark setext H1
+ * underline of exactly 7 `=` characters: `My Title\n=======`).
+ *
+ * Used by the `?source=ytext` branch of the conflict-content handler to
+ * decide whether the live Y.Text snapshot is usable as `ours` (no marker
+ * triple → safe to surface live edits) or polluted by the file watcher's
+ * reopen-time disk seed (triple present → fall back to git-index `ours`).
+ */
+function ytextHasConflictMarkers(text: string): boolean {
+ return /^<{7} /m.test(text) && /^={7}$/m.test(text) && /^>{7} /m.test(text);
+}
+
+export interface SyncRouteDeps {
+ projectDir: string | undefined;
+ hocuspocus: Hocuspocus;
+ log: PinoLogger;
+ /** The extension's shared local-op security gate (emits RFC 9457 on refusal). */
+ checkLocalOpSecurity: (
+ req: IncomingMessage,
+ res: ServerResponse,
+ opts: { handler: string },
+ ) => boolean;
+ getSyncEngine: (() => SyncEngine | null) | undefined;
+ /** Live Y.Text snapshot for a loaded doc, or null when unavailable. */
+ serializeDoc: ((docName: string) => string | null) | undefined;
+}
+
+export function createSyncRoutes(deps: SyncRouteDeps): ApiRouteGroup {
+ const { projectDir, hocuspocus, log, checkLocalOpSecurity, getSyncEngine, serializeDoc } = deps;
+
+ async function handleSyncStatus(req: IncomingMessage, res: ServerResponse): Promise<void> {
+ if (!checkLocalOpSecurity(req, res, { handler: 'sync-status' })) return;
+ if (req.method !== 'GET') {
+ errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {
+ handler: 'sync-status',
+ extraHeaders: { Allow: 'GET' },
+ });
+ return;
+ }
+ try {
+ const engine = getSyncEngine?.();
+ if (!engine) {
+ // Shape must stay aligned with SyncStatus (see sync-engine.ts) — the UI
+ // reads these fields unconditionally. Dormant fallback when the engine
+ // isn't constructed (no remote, sync disabled at boot).
+ successResponse(
+ res,
+ 200,
+ SyncStatusSchema,
+ {
+ state: 'dormant',
+ lastSyncUtc: null,
+ lastFetchUtc: null,
+ lastPushedSha: null,
+ ahead: 0,
+ behind: 0,
+ consecutiveFailures: 0,
+ conflictCount: 0,
+ hasRemote: false,
+ syncEnabled: false,
+ identityUnresolved: false,
+ remote: null,
+ },
+ { handler: 'sync-status' },
+ );
+ return;
+ }
+ // Lazy remote re-detection: if the user ran `git remote add origin <url>`
+ // after the server booted, refresh `hasRemote` so the Settings → Sync
+ // empty state and badge update without an app restart. No-op once a
+ // remote has been observed.
+ await engine.refreshRemote();
+ successResponse(res, 200, SyncStatusSchema, engine.getStatus(), {
+ handler: 'sync-status',
+ });
+ } catch (e) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'sync-status',
+ cause: e,
+ });
+ }
+ }
+
+ const handleSyncTrigger = withValidation(
+ SyncTriggerRequestSchema,
+ async (_req, res, body) => {
+ const engine = getSyncEngine?.();
+ if (!engine) {
+ // Race-window guard: the preBodyGate confirmed the engine was active,
+ // but it could have been torn down between gate and inner-handler
+ // invocation. Treat as 503 — same as the gate would have.
+ errorResponse(res, 503, 'urn:ok:error:sync-not-active', 'Sync engine not active.', {
+ handler: 'sync-trigger',
+ });
+ return;
+ }
+ const op = body.op ?? 'sync';
+ // Fire-and-return: 202 Accepted immediately, trigger runs in background.
+ successResponse(res, 202, SyncTriggerSuccessSchema, { op }, { handler: 'sync-trigger' });
+ // `.catch` is mandatory on every fire-and-forget trigger: the response has
+ // already been sent, so a rejection has nowhere to go but the process.
+ void engine.trigger(op).catch((err) => {
+ log.error({ err, op }, '[sync] fire-and-forget trigger failed');
+ });
+ },
+ {
+ handler: 'sync-trigger',
+ method: 'POST',
+ preBodyGate: (req, res) => {
+ if (!checkLocalOpSecurity(req, res, { handler: 'sync-trigger' })) return false;
+ const engine = getSyncEngine?.();
+ if (!engine) {
+ errorResponse(res, 503, 'urn:ok:error:sync-not-active', 'Sync engine not active.', {
+ handler: 'sync-trigger',
+ });
+ return false;
+ }
+ return true;
+ },
+ },
+ );
+
+ /**
+ * `POST /api/sync/resolve-blocking` — clear a pre-merge overlap pause by
+ * committing the local edits that caused it, then resume.
+ *
+ * The body names an ACTION and nothing else. The paths come from the
+ * engine's blocking set, so this cannot be aimed: a body-supplied path list
+ * would make `discard` a general-purpose "throw away this file's edits"
+ * endpoint reachable from any page the user's browser has open. Empty set →
+ * 409 rather than a silent success, because a UI offering these buttons
+ * against a pause that already cleared is showing the user stale state.
+ *
+ * The follow-up trigger is the point of the button: `commit` runs a full
+ * sync, because the commit it just authored is now outgoing work.
+ *
+ * `commit` is the only action the schema admits. A `discard` verb is
+ * deliberately withheld until a recoverable snapshot exists behind it —
+ * restoring the blocking paths leaves no reflog entry to recover from.
+ */
+ const handleSyncResolveBlocking = withValidation(
+ SyncResolveBlockingRequestSchema,
+ // `body` is unread: the schema admits exactly one action, and the paths come
+ // from engine state rather than the request (see the docblock above).
+ async (_req, res, _body) => {
+ const engine = getSyncEngine?.();
+ if (!engine) {
+ errorResponse(res, 503, 'urn:ok:error:sync-not-active', 'Sync engine not active.', {
+ handler: 'sync-resolve-blocking',
+ });
+ return;
+ }
+ if (engine.getBlockingPaths().length === 0) {
+ errorResponse(
+ res,
+ 409,
+ 'urn:ok:error:no-blocking-changes',
+ 'No local changes are blocking a merge.',
+ {
+ handler: 'sync-resolve-blocking',
+ },
+ );
+ return;
+ }
+ try {
+ // `commit` is the only action. A `discard` verb was deliberately not
+ // shipped: reverting uncommitted work is unrecoverable (git keeps no
+ // reflog for it), and the destructive verb waits on a recoverable
+ // snapshot landing first. The schema rejects anything else before this
+ // point, so there is no second branch to fall through to.
+ const paths = engine.getBlockingPaths();
+ const commitSha = await engine.commitBlockingPaths();
+ successResponse(
+ res,
+ 200,
+ SyncResolveBlockingSuccessSchema,
+ { action: 'commit', paths, ...(commitSha !== null ? { commitSha } : {}) },
+ { handler: 'sync-resolve-blocking' },
+ );
+ void engine.trigger('sync').catch((err) => {
+ log.error({ err }, '[sync] resolve-blocking follow-up sync failed');
+ });
+ } catch (e) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'sync-resolve-blocking',
+ cause: e,
+ });
+ }
+ },
+ {
+ handler: 'sync-resolve-blocking',
+ method: 'POST',
+ preBodyGate: (req, res) =>
+ checkLocalOpSecurity(req, res, { handler: 'sync-resolve-blocking' }),
+ },
+ );
+
+ async function handleSyncConflicts(req: IncomingMessage, res: ServerResponse): Promise<void> {
+ if (!checkLocalOpSecurity(req, res, { handler: 'sync-conflicts' })) return;
+ if (req.method !== 'GET') {
+ errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {
+ handler: 'sync-conflicts',
+ extraHeaders: { Allow: 'GET' },
+ });
+ return;
+ }
+ try {
+ const engine = getSyncEngine?.();
+ const conflicts = engine ? engine.getConflicts() : [];
+ successResponse(
+ res,
+ 200,
+ SyncConflictsSuccessSchema,
+ { conflicts },
+ {
+ handler: 'sync-conflicts',
+ },
+ );
+ } catch (e) {
+ errorResponse(res, 500, 'urn:ok:error:internal-server-error', 'Internal server error.', {
+ handler: 'sync-conflicts',
+ cause: e,
+ });
+ }
+ }
+
+ const handleSyncResolveConflict = withValidation(
+ SyncResolveConflictRequestSchema,
+ async (_req, res, body) => {
+ const engine = getSyncEngine?.();
+ if (!engine) {
+ // Race-window guard — see HANDLE_SYNC_TRIGGER comment.
+ errorResponse(res, 503, 'urn:ok:error:sync-not-active', 'Sync engine not active.', {
+ handler: 'sync-resolve-conflict',
+ });
+ return;
+ }
+ const { file, strategy, content } = body;
+ try {
+ await engine.resolveConflict(file, strategy as ResolveStrategy, content);
+ successResponse(
+ res,
+ 200,
+ SyncResolveConflictSuccessSchema,
+ {},
+ {
+ handler: 'sync-resolve-conflict',
+ },
+ );
+ } catch (e) {
+ // Surface the underlying error (typically the git commit stderr
+ // wrapped by `ConflictStore.resolveConflict`) on the RFC 9457
+ // `detail` field so operators + UI toasts + agent tools have the
+ // diagnostic context — without this, every commit failure looks
+ // identical at the client.
+ const detail = e instanceof Error ? e.message : undefined;
+ errorResponse(
+ res,
+ 500,
+ 'urn:ok:error:internal-server-error',
+ 'Failed to resolve conflict.',
+ {
+ handler: 'sync-resolve-conflict',
+ cause: e,
+ detail,
+ },
+ );
+ }
+ },
+ {
+ handler: 'sync-resolve-conflict',
+ method: 'POST',
+ preBodyGate: (req, res) => {
+ if (!checkLocalOpSecurity(req, res, { handler: 'sync-resolve-conflict' })) return false;
+ const engine = getSyncEngine?.();
+ if (!engine) {
+ errorResponse(res, 503, 'urn:ok:error:sync-not-active', 'Sync engine not active.', {
+ handler: 'sync-resolve-conflict',
+ });
+ return false;
+ }
+ return true;
+ },
+ },
+ );
+
+ async function handleSyncConflictContent(
+ req: IncomingMessage,
+ res: ServerResponse,
+ ): Promise<void> {
+ if (!checkLocalOpSecurity(req, res, { handler: 'sync-conflict-content' })) return;
+ if (req.method !== 'GET') {
+ errorResponse(res, 405, 'urn:ok:error:method-not-allowed', 'Method not allowed.', {
+ handler: 'sync-conflict-content',
+ extraHeaders: { Allow: 'GET' },
+ });
+ return;
+ }
+ if (!projectDir) {
+ errorResponse(
+ res,
+ 503,
+ 'urn:ok:error:project-repo-not-configured',
+ 'Project repo not configured.',
+ { handler: 'sync-conflict-content' },
+ );
+ return;
+ }
+ const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+ const file = url.searchParams.get('file');
+ if (!file) {
+ errorResponse(
+ res,
+ 400,
+ 'urn:ok:error:invalid-request',
+ 'Missing required query param: file.',
+ {
+ handler: 'sync-conflict-content',
+ },
+ );
+ return;
+ }
+ // Reject obvious path-traversal; git itself rejects paths outside the index.
+ if (file.includes('..') || file.startsWith('/')) {
+ errorResponse(res, 400, 'urn:ok:error:invalid-request', 'Invalid file path.', {
+ handler: 'sync-conflict-content',
+ });
+ return;
+ }
+ // Refuse the request when no conflict is tracked for the path. Without
+ // this gate, the git stage reads silently return empty strings for
+ // untracked files, producing a 200 response with empty base/ours/theirs
+ // — misleading to agents that took the file path from a stale 409
+ // envelope or have inconsistent state. The tool description on
+ // `conflicts({ kind: 'content' })` documents this 404; the gate enforces it.
+ //
+ // Authority is split between two sources that normally agree but can
+ // diverge in tests / external-git scenarios: (a) ConflictStore via the
+ // SyncEngine — populated when SyncEngine merges; and (b) the doc's
+ // `lifecycle.status` Y.Map — set by the file-watcher's `case 'conflict'`
+ // branch even when SyncEngine wasn't involved (markers landed on disk
+ // via external git ops). Accept EITHER as authoritative tracking.
+ const trackedDocName = stripDocExtension(file);
+ const loadedDoc = hocuspocus.documents.get(trackedDocName);
+ const isConflictedByLifecycle = loadedDoc?.getMap('lifecycle').get('status') === 'conflict';
+ const engine = getSyncEngine?.();
+ const isTrackedByStore = engine ? engine.getConflicts().some((c) => c.file === file) : false;
+ if (!isConflictedByLifecycle && !isTrackedByStore) {
+ errorResponse(
+ res,
+ 404,
+ 'urn:ok:error:no-conflict-tracked',
+ 'No conflict is tracked for this path.',
+ {
+ handler: 'sync-conflict-content',
+ extensions: { file },
+ },
+ );
+ return;
+ }
+ // Optional `?source=ytext` override: when the requested file maps to
+ // a loaded doc, serve `ours` from the live Y.Text snapshot rather
+ // than the git index. Covers the pre-conflict-unflushed-edits case
+ // where Y.Text holds bytes the user typed after the last persistence
+ // flush (persistence-during-conflict skip means those bytes don't
+ // reach disk during conflict). Any other value (or no value) falls
+ // back to the default `git show :2:` path so existing callers stay
+ // backward-compatible.
+ const source = url.searchParams.get('source');
+ const pg = simpleGit({ baseDir: projectDir, timeout: { block: 15_000 } });
+
+ // Working-tree-variant conflicts (pull-only B1) have no git index stages:
+ // the branch already fast-forwarded to origin tip and the overlay rides
+ // uncommitted on top. Serve `theirs`/`base` from the pinned tip/base blobs
+ // and `ours` from the live doc (or disk when unloaded). The merge-native
+ // stage path below is untouched for git-merge conflicts.
+ const wtEntry = engine
+ ?.getConflicts()
+ .find((c) => c.file === file && c.variant === 'working-tree');
+ if (wtEntry) {
+ try {
+ // A pinned SHA that fails to read is an unexpected failure (the blob was
+ // reachable when the engine pinned it), NOT an absent blob. Returning ''
+ // would misread it downstream as origin-deleted (`kind: 'modify-delete'`)
+ // and steer the user into a `delete` resolution that removes their own
+ // doc. Discriminate: `undefined` sha = genuinely no pinned blob (the
+ // empty side of a delete/modify); a read failure on a present sha logs
+ // and rethrows to the outer catch → 500, matching the merge-native
+ // `showStage` discipline below.
+ const readBlob = async (sha: string | undefined): Promise<string> => {
+ if (!sha) return '';
+ try {
+ return await pg.raw(['cat-file', 'blob', sha]);
+ } catch (err) {
+ console.warn(
+ JSON.stringify({
+ event: 'conflict-content-readblob-failed',
+ file,
+ detail: err instanceof Error ? err.message : String(err),
+ handler: 'sync-conflict-content',
+ }),
+ );
+ throw err;
+ }
+ };
+ const theirs = await readBlob(wtEntry.theirsSha);
+ const base = await readBlob(wtEntry.baseSha);
+ const docName = stripDocExtension(file);
+ const loaded = hocuspocus.documents.get(docName);
+ let ours = '';
+ let oursPresent = false;
+ let lifecycleStatus: string | null = null;
+ if (loaded) {
+ const rawStatus = loaded.getMap('lifecycle').get('status');
+ lifecycleStatus =
+ typeof rawStatus === 'string' && rawStatus.length > 0 ? rawStatus : null;
+ const ytextOurs = serializeDoc ? serializeDoc(docName) : null;
+ if (ytextOurs !== null) {
+ ours = ytextOurs;
+ oursPresent = true;
+ }
+ } else {
+ // Unloaded doc: the overlay is on disk (absent for a delete overlay).
+ // Realpath-contain the read first — `file` is an origin-controlled
+ // tracked path that could be a symlink escaping the working tree,
+ // disclosing a foreign file. A SymlinkEscapeError propagates to the
+ // outer catch → 500; the inner catch still handles the benign ENOENT
+ // of a genuine delete overlay.
+ // `allowShareableOkArtifact` matches the write sites in conflict-storage.
+ // Without it a root-`.ok` conflict (now pinnable — `.ok/templates/*` is a
+ // shareable artifact) throws SymlinkEscapeError here and surfaces as a
+ // 500, wedging the project: the push gate holds while conflicts exist and
+ // the conflict cannot be inspected to resolve it. `docs/.ok/...` was
+ // unaffected, so a nested fixture would not have caught it.
+ assertRealpathWithinDir(join(projectDir, file), projectDir, {
+ allowShareableOkArtifact: isShareableOkArtifact,
+ });
+ try {
+ ours = readFileSync(join(projectDir, file), 'utf-8');
+ oursPresent = true;
+ } catch (err) {
+ // Only a genuine ENOENT is the empty side of a delete overlay
+ // (`oursPresent=false` → `delete-modify`). Any other failure
+ // (EACCES, EIO, a transient hiccup) misread as a delete would steer
+ // the UI into `git rm`-ing the user's own doc — the exact
+ // misclassification `readBlob` above and `showStage` below are
+ // written to prevent — so log and rethrow to the outer catch → 500.
+ if (errnoCode(err) !== 'ENOENT') {
+ console.warn(
+ JSON.stringify({
+ event: 'conflict-content-ours-read-failed',
+ file,
+ detail: err instanceof Error ? err.message : String(err),
+ handler: 'sync-conflict-content',
+ }),
+ );
+ throw err;
+ }
+ oursPresent = false;
+ }
+ }
+ // A locally-deleted file the tip modified is a delete/modify shape;
+ // otherwise both sides hold content.
+ const kind: 'both-modified' | 'delete-modify' | 'modify-delete' = !oursPresent
+ ? 'delete-modify'
+ : theirs.length === 0
+ ? 'modify-delete'
+ : 'both-modified';
+ successResponse(
+ res,
+ 200,
+ SyncConflictContentSuccessSchema,
+ { file, base, ours, theirs, kind, lifecycleStatus },
+ { handler: 'sync-conflict-content' },
+ );
+ } catch (e) {
+ errorResponse(
+ res,
+ 500,
+ 'urn:ok:error:internal-server-error',
+ 'Failed to read conflict content.',
+ { handler: 'sync-conflict-content', cause: e },
+ );
+ }
+ return;
+ }
+
+ // git stages: 1 = base, 2 = ours, 3 = theirs. Any may be missing for
+ // delete/edit or add/add conflicts. Return a discriminated shape so the
+ // caller can derive `kind` from stage presence — empty-string content is
+ // otherwise indistinguishable from a legitimately-empty file, and the
+ // earlier swallow-and-return-`''` shape silently mapped DU/UD into the
+ // both-modified path.
+ type StageResult = { present: false } | { present: true; content: string };
+ // Discriminate "stage genuinely absent" (expected for DU/UD) from
+ // "git subprocess failed" (transient: timeout, permissions, corruption).
+ // Both map to `{ present: false }` and the caller derives `kind` from
+ // it — without this discrimination, a transient git error silently
+ // sets `kind` to `'delete-modify'`, the UI renders "Keep deletion" for
+ // a file the user actually edited, and clicking it `git rm`s the file.
+ // Log unexpected errors loudly so "user lost work after resolution"
+ // incidents have a paper trail.
+ async function showStage(stage: 1 | 2 | 3): Promise<StageResult> {
+ try {
+ return { present: true, content: await pg.raw(['show', `:${stage}:${file}`]) };
+ } catch (err) {
+ const msg = err instanceof Error ? err.message : String(err);
+ // Expected "stage absent" git error shapes from simple-git's stderr
+ // passthrough. Observed in practice:
+ // - "pathspec '...' did not match any files known to git"
+ // - "path '...' is in the index, but not at stage <N>"
+ // - "path '...' exists on disk, but not in '<ref>'"
+ // Full-phrase matches only — short fragments like "but not in"
+ // alone could false-match unrelated git errors and silently
+ // return `{ present: false }` for a real failure (data-loss
+ // class). Locale-stable English fragments — git messages are
+ // English-only.
+ const isAbsent =
+ /pathspec|did not match|exists on disk, but not in|is in the index, but not at stage/i.test(
+ msg,
+ );
+ if (!isAbsent) {
+ // Unexpected git failure (timeout, object corruption, permission,
+ // EMFILE). Returning `{ present: false }` would drive `kind`
+ // derivation downstream silently — a transient stage-2 failure
+ // on a both-modified conflict would produce
+ // `kind: 'delete-modify'`, the UI would render "Keep file
+ // deleted" + "Restore with remote changes", and clicking
+ // "Keep file deleted" would `git rm` a file the user edited.
+ // Rethrow so the outer try converts to a 500;
+ // the UI's `fetchFailed` state ("Couldn't load conflict
+ // content — try reloading") handles it visibly.
+ console.warn(
+ JSON.stringify({
+ event: 'showstage-unexpected-error',
+ stage,
+ file,
+ detail: msg,
+ handler: 'sync-conflict-content',
+ }),
+ );
+ throw err;
+ }
+ return { present: false };
+ }
+ }
+ try {
+ const [baseResult, oursResult, theirsResult] = await Promise.all([
+ showStage(1),
+ showStage(2),
+ showStage(3),
+ ]);
+ const base = baseResult.present ? baseResult.content : '';
+ const theirs = theirsResult.present ? theirsResult.content : '';
+ // Derive the stage-presence discriminator. Reaching this handler
+ // requires the conflict-tracked guard above, so
+ // at least one of stages 2/3 is always present — `neither` is
+ // unreachable at runtime. The four branches are enumerated
+ // explicitly (rather than collapsed into a trailing else) so the
+ // `(false, false)` branch is self-documenting: it surfaces
+ // `'both-modified'` as a defensive default; the caller branches
+ // safely off that without a load-bearing assertNever.
+ const kind: 'both-modified' | 'delete-modify' | 'modify-delete' =
+ oursResult.present && theirsResult.present
+ ? 'both-modified'
+ : !oursResult.present && theirsResult.present
+ ? 'delete-modify'
+ : oursResult.present && !theirsResult.present
+ ? 'modify-delete'
+ : 'both-modified';
+ let ours = oursResult.present ? oursResult.content : '';
+ // Surface `lifecycleStatus` when the doc is loaded server-side so the
+ // MCP `conflicts({ kind: 'content' })` caller can detect post-resolution state
+ // (status === null after the conflict clears) without a second
+ // round-trip. Only meaningful in the `source=ytext` branch — the
+ // default `git show :2:` path is callable without a loaded doc.
+ let lifecycleStatus: string | null = null;
+ if (source === 'ytext') {
+ const docName = stripDocExtension(file);
+ const loaded = hocuspocus.documents.get(docName);
+ if (loaded) {
+ const rawStatus = loaded.getMap('lifecycle').get('status');
+ lifecycleStatus =
+ typeof rawStatus === 'string' && rawStatus.length > 0 ? rawStatus : null;
+ // Gate the Y.Text substitution on the `kind` shape. The narrow
+ // risk that motivated the gate: for DU (delete-modify, stage 2
+ // absent), the file-watcher seeded Y.Text with `theirs` content
+ // from disk (git leaves the remote version in the working tree
+ // on modify/delete conflicts). Substituting Y.Text into `ours`
+ // would equal `theirs` and silently un-delete the local intent.
+ // Honest path for DU: leave `ours` empty; the `kind` discriminator
+ // drives the UI affordance.
+ //
+ // For every OTHER shape — both-modified (real merge), modify-
+ // delete (stage 2 present, only theirs absent), and the legacy
+ // filesystem-marker conflict path (neither stage in git index;
+ // `case 'conflict'` in the file-watcher fires on disk-markers
+ // without a real merge) — Y.Text substitution is correct and
+ // load-bearing. A previous `oursResult.present` gate over-
+ // restricted: it broke the filesystem-marker case where a
+ // mid-conflict Y.Text edit must surface despite no git stages
+ // existing in the index.
+ if (kind !== 'delete-modify') {
+ const ytextOurs = serializeDoc ? serializeDoc(docName) : null;
+ if (ytextOurs !== null && !ytextHasConflictMarkers(ytextOurs)) {
+ ours = ytextOurs;
+ } else if (ytextOurs !== null) {
+ // Structured signal so triage can spot when the marker-triple
+ // detection fired and the handler fell back to git-index — the
+ // alternative is silent. Pairs with `doc.name` for the
+ // affected document.
+ console.warn(
+ JSON.stringify({
+ event: 'ytext-conflict-marker-detected',
+ 'doc.name': docName,
+ handler: 'sync-conflict-content',
+ }),
+ );
+ }
+ }
+ } else {
+ log.warn(
+ { docName },
+ `[conflict-content] doc ${docName} not loaded; lifecycleStatus unavailable`,
+ );
+ }
+ }
+ successResponse(
+ res,
+ 200,
+ SyncConflictContentSuccessSchema,
+ { file, base, ours, theirs, kind, lifecycleStatus },
+ { handler: 'sync-conflict-content' },
+ );
+ } catch (e) {
+ errorResponse(
+ res,
+ 500,
+ 'urn:ok:error:internal-server-error',
+ 'Failed to read conflict content.',
+ {
+ handler: 'sync-conflict-content',
+ cause: e,
+ },
+ );
+ }
+ }
+
+ const routes = {
+ '/api/sync/status': handleSyncStatus,
+ '/api/sync/trigger': handleSyncTrigger,
+ '/api/sync/conflicts': handleSyncConflicts,
+ '/api/sync/conflict-content': handleSyncConflictContent,
+ '/api/sync/resolve-conflict': handleSyncResolveConflict,
+ '/api/sync/resolve-blocking': handleSyncResolveBlocking,
+ } satisfies ApiRouteRecord;
+
+ return createApiRouteGroup(routes, {
+ mutating: ['/api/sync/trigger', '/api/sync/resolve-conflict', '/api/sync/resolve-blocking'],
+ });
+}
diff --git a/packages/server/src/local-op-security.ts b/packages/server/src/local-op-security.ts
index 239d651ef..2b3dc4e03 100644
--- a/packages/server/src/local-op-security.ts
+++ b/packages/server/src/local-op-security.ts
@@ -331,7 +331,7 @@ export function checkLocalOpSecurity(
* if (!guard.tryAcquire('/api/local-op/clone')) { /* already in flight *\/ }
* try { … } finally { guard.release('/api/local-op/clone'); }
*/
-interface ConcurrencyGuard {
+export interface ConcurrencyGuard {
tryAcquire(key: string): boolean;
release(key: string): void;
}
diff --git a/packages/server/src/local-ops/subprocess.ts b/packages/server/src/local-ops/subprocess.ts
index 4eb105107..3170a7e89 100644
--- a/packages/server/src/local-ops/subprocess.ts
+++ b/packages/server/src/local-ops/subprocess.ts
@@ -7,8 +7,20 @@
* lines as needed.
*
* Lifetime: the returned controller's `cancel()` sends SIGTERM. The runner
- * resolves with `{ code, stderr }` once the child exits, regardless of
- * cancellation.
+ * resolves with `{ code, stderr }` once the child's stdio has closed,
+ * regardless of cancellation.
+ *
+ * KNOWN GAP (deferred, deliberately — the Wave 2 settled-latch adoption
+ * stopped at the HTTP handlers): settlement here still depends on the child
+ * cooperating — the timeout sends SIGTERM without being a settle branch, so
+ * a signal-resistant or wedged child leaves `done` pending. That failure class reaches every consumer of this chokepoint: the
+ * six HTTP local-op endpoints routed through it, plus
+ * `local-ops/auth-query.ts` (`runAuthStatusSubprocess` /
+ * `runAuthReposSubprocess`) and the desktop IPC surface
+ * (`packages/desktop/src/main/index.ts`) that calls them — a surface the
+ * HTTP-side fixes do not cover.
+ * `auth-query.ts` also carries its own duplicate `DEFAULT_TIMEOUT_MS =
+ * 30_000`; fold it into the same follow-up.
*/
import { spawn } from 'node:child_process';
@@ -65,7 +77,7 @@ interface SubprocessRunResult {
}
interface SubprocessController {
- /** Promise that resolves once the child has exited (success or otherwise). */
+ /** Promise that resolves once the child's stdio has closed (success or otherwise). */
done: Promise<SubprocessRunResult>;
/** SIGTERM the child. Idempotent. */
cancel(): void;