Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Fix directory identity for saves and file discovery (#5520)

Nick Gomezd6d49ca7fccb
diff --git a/.changeset/directory-alias-saves.md b/.changeset/directory-alias-saves.md
new file mode 100644
index 000000000..ed4a9cc03
--- /dev/null
+++ b/.changeset/directory-alias-saves.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+When a folder is opened using another spelling of its path, edits are saved, links and embeds find existing files, and diagnostic bundles mask both spellings of that path.
diff --git a/packages/app/tests/meta/link-audit-seams.manifest.ts b/packages/app/tests/meta/link-audit-seams.manifest.ts
index 7fd1e7fe4..f3d3cbbf4 100644
--- a/packages/app/tests/meta/link-audit-seams.manifest.ts
+++ b/packages/app/tests/meta/link-audit-seams.manifest.ts
@@ -212,7 +212,7 @@ export interface LinkAuditCompositionRoot {
export const LINK_AUDIT_COMPOSITION_ROOTS: readonly LinkAuditCompositionRoot[] = [
{
path: 'packages/server/src/server-factory.ts',
- requiredText: 'localTargetInventoryFromWatcher(watcher, contentDir)',
+ requiredText: 'localTargetInventoryFromWatcher(watcher, canonicalContentDir)',
},
{
path: 'packages/server/src/http/link-graph-routes.ts',
diff --git a/packages/cli/src/diagnose/bundle-redact.ts b/packages/cli/src/diagnose/bundle-redact.ts
index b54d72fa8..55b5af846 100644
--- a/packages/cli/src/diagnose/bundle-redact.ts
+++ b/packages/cli/src/diagnose/bundle-redact.ts
@@ -1,4 +1,4 @@
-import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { readdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
import { basename, join } from 'node:path';
const CONTENT_DIR_TOKEN = '<CONTENT_DIR>';
@@ -9,13 +9,27 @@ export interface RedactStagedBundleOpts {
}
interface RedactCtx {
- contentDir: string;
+ contentDirSpellings: readonly string[];
+}
+
+export function contentDirSpellings(contentDir: string): readonly string[] {
+ const spellings = new Set([contentDir]);
+ try {
+ spellings.add(realpathSync.native(contentDir));
+ } catch {
+ return [contentDir].filter((spelling) => spelling.length > 0);
+ }
+ return [...spellings]
+ .filter((spelling) => spelling.length > 0)
+ .sort((a, b) => b.length - a.length);
}
-function replaceContentDir(value: string, contentDir: string): string {
- if (contentDir.length === 0) return value;
- if (!value.includes(contentDir)) return value;
- return value.split(contentDir).join(CONTENT_DIR_TOKEN);
+function replaceContentDir(value: string, spellings: readonly string[]): string {
+ let result = value;
+ for (const spelling of spellings) {
+ if (result.includes(spelling)) result = result.split(spelling).join(CONTENT_DIR_TOKEN);
+ }
+ return result;
}
function isObject(v: unknown): v is Record<string, unknown> {
@@ -24,7 +38,7 @@ function isObject(v: unknown): v is Record<string, unknown> {
function redactValue(node: unknown, ctx: RedactCtx): unknown {
if (typeof node === 'string') {
- return replaceContentDir(node, ctx.contentDir);
+ return replaceContentDir(node, ctx.contentDirSpellings);
}
if (Array.isArray(node)) {
return node.map((item) => redactValue(item, ctx));
@@ -73,14 +87,14 @@ function redactJsonFile(filePath: string, ctx: RedactCtx): void {
const trailingNewline = content.endsWith('\n') ? '\n' : '';
writeFileSync(filePath, `${JSON.stringify(redacted, null, 2)}${trailingNewline}`);
} catch {
- const replaced = replaceContentDir(content, ctx.contentDir);
+ const replaced = replaceContentDir(content, ctx.contentDirSpellings);
if (replaced !== content) writeFileSync(filePath, replaced);
}
}
function redactPlainFile(filePath: string, ctx: RedactCtx): void {
const content = readFileSync(filePath, 'utf-8');
- const replaced = replaceContentDir(content, ctx.contentDir);
+ const replaced = replaceContentDir(content, ctx.contentDirSpellings);
if (replaced !== content) writeFileSync(filePath, replaced);
}
@@ -112,7 +126,7 @@ export const CONTENT_SUBDIRS_MASKED = [
] as const;
export function redactStagedBundle(opts: RedactStagedBundleOpts): void {
- const ctx: RedactCtx = { contentDir: opts.contentDir };
+ const ctx: RedactCtx = { contentDirSpellings: contentDirSpellings(opts.contentDir) };
for (const subdir of CONTENT_SUBDIRS_MASKED) {
for (const filePath of walkDirFiles(join(opts.stagingDir, subdir))) {
diff --git a/packages/cli/src/diagnose/bundle.test.ts b/packages/cli/src/diagnose/bundle.test.ts
index 569df4d23..95c476f06 100644
--- a/packages/cli/src/diagnose/bundle.test.ts
+++ b/packages/cli/src/diagnose/bundle.test.ts
@@ -5,12 +5,15 @@ import {
mkdtempSync,
readdirSync,
readFileSync,
+ realpathSync,
rmSync,
+ statSync,
+ symlinkSync,
writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { afterEach, describe, expect, test } from 'vitest';
+import { dirname, join, resolve, sep } from 'node:path';
+import { afterEach, describe, expect, onTestFinished, test } from 'vitest';
import { ZipFile } from 'yazl';
import type { LanguageMetadata } from '../report-language.ts';
import {
@@ -703,6 +706,185 @@ describe('collectBundle — summary', () => {
});
});
+type SpellingRelation = 'same' | 'disjoint' | 'typed-within-native' | 'native-within-typed';
+
+function spellingRelation(typed: string, native: string): SpellingRelation {
+ if (typed === native) return 'same';
+ if (native.includes(typed)) return 'typed-within-native';
+ if (typed.includes(native)) return 'native-within-typed';
+ return 'disjoint';
+}
+
+function makeAliasedRoot(
+ link: string,
+ target: string,
+): { projectDir: string; typed: string; native: string } {
+ const projectDir = realpathSync.native(makeTmpDir('ok-bundle-alias-'));
+ const real = join(projectDir, target);
+ mkdirSync(real);
+ const typed = join(projectDir, link);
+ symlinkSync(real, typed, process.platform === 'win32' ? 'junction' : 'dir');
+ return { projectDir, typed, native: realpathSync.native(typed) };
+}
+
+function jsonl(lines: readonly Record<string, unknown>[]): string {
+ return lines.map((line) => `${JSON.stringify(line)}\n`).join('');
+}
+
+function readStagedJsonl(stagingDir: string, relPath: string): unknown[] {
+ return readFileSync(join(stagingDir, relPath), 'utf-8')
+ .trim()
+ .split('\n')
+ .map((line) => JSON.parse(line));
+}
+
+describe('collectBundle — a content root typed through a directory alias', () => {
+ test.each([
+ { shape: 'unrelated names', link: 'notes-link', target: 'vault', relation: 'disjoint' },
+ {
+ shape: 'link name prefixes the target name',
+ link: 'notes',
+ target: 'notes-real',
+ relation: 'typed-within-native',
+ },
+ {
+ shape: 'target name prefixes the link name',
+ link: 'notes-link',
+ target: 'notes',
+ relation: 'native-within-typed',
+ },
+ ] as const)(
+ 'redaction masks both the typed and the native spelling of the root ($shape)',
+ async ({ link, target, relation }) => {
+ const { projectDir, typed, native } = makeAliasedRoot(link, target);
+ expect(spellingRelation(typed, native)).toBe(relation);
+ writeAt(
+ projectDir,
+ '.ok/local/logs/server-current.jsonl',
+ jsonl([
+ {
+ level: 30,
+ contentDir: native,
+ backend: 'parcel',
+ msg: 'watching for external .md changes',
+ },
+ {
+ level: 20,
+ kind: 'change',
+ path: join(native, 'note.md'),
+ msg: '[file-watcher] Dispatching: change',
+ },
+ { level: 30, path: join(typed, 'note.md'), msg: 'opened' },
+ ]),
+ );
+ const processDir = makeTmpDir('ok-bundle-procsrc-');
+ writeFileSync(
+ join(processDir, 'lsof.txt'),
+ `node 4242 jane cwd DIR ${native}\nnode 4242 jane 21r REG ${join(typed, 'note.md')}\n`,
+ );
+
+ const collected = await collectBundle({
+ contentDir: typed,
+ projectDir,
+ processDir,
+ redact: true,
+ deps: makeDeterministicDeps(),
+ });
+ onTestFinished(() => collected.cleanup());
+
+ expect
+ .soft(readStagedJsonl(collected.stagingDir, 'logs/server-current.jsonl'), 'server log')
+ .toEqual([
+ {
+ level: 30,
+ contentDir: '<CONTENT_DIR>',
+ backend: 'parcel',
+ msg: 'watching for external .md changes',
+ },
+ {
+ level: 20,
+ kind: 'change',
+ path: `<CONTENT_DIR>${sep}note.md`,
+ msg: '[file-watcher] Dispatching: change',
+ },
+ { level: 30, path: `<CONTENT_DIR>${sep}note.md`, msg: 'opened' },
+ ]);
+ expect
+ .soft(readFileSync(join(collected.stagingDir, 'process', 'lsof.txt'), 'utf-8'), 'lsof')
+ .toBe(
+ `node 4242 jane cwd DIR <CONTENT_DIR>\nnode 4242 jane 21r REG <CONTENT_DIR>${sep}note.md\n`,
+ );
+ },
+ );
+
+ test('contentDirVisible reports a root that appears only in its native spelling', async () => {
+ const { projectDir, typed, native } = makeAliasedRoot('notes-link', 'vault');
+ expect(spellingRelation(typed, native)).toBe('disjoint');
+ const processDir = makeTmpDir('ok-bundle-procsrc-');
+ writeFileSync(join(processDir, 'lsof.txt'), `node 4242 jane cwd DIR ${native}\n`);
+
+ const collected = await collectBundle({
+ contentDir: typed,
+ projectDir,
+ processDir,
+ deps: makeDeterministicDeps(),
+ });
+ onTestFinished(() => collected.cleanup());
+
+ expect(readFileSync(join(collected.stagingDir, 'process', 'lsof.txt'), 'utf-8')).toBe(
+ `node 4242 jane cwd DIR ${native}\n`,
+ );
+ expect(collected.summary.contentDirVisible).toBe(true);
+ });
+
+ test('redaction still masks the typed spelling of a root that does not exist on disk', async () => {
+ const projectDir = makeTmpDir();
+ const contentDir = join(projectDir, 'notes-not-created');
+ expect(existsSync(contentDir)).toBe(false);
+ writeAt(
+ projectDir,
+ '.ok/local/logs/server-current.jsonl',
+ jsonl([{ level: 30, path: join(contentDir, 'note.md'), msg: 'opened' }]),
+ );
+
+ const collected = await collectBundle({
+ contentDir,
+ projectDir,
+ redact: true,
+ deps: makeDeterministicDeps(),
+ });
+ onTestFinished(() => collected.cleanup());
+
+ expect(readStagedJsonl(collected.stagingDir, 'logs/server-current.jsonl')).toEqual([
+ { level: 30, path: `<CONTENT_DIR>${sep}note.md`, msg: 'opened' },
+ ]);
+ });
+
+ test('redaction still masks the typed spelling of a root whose path runs through a file', async () => {
+ const projectDir = makeTmpDir();
+ writeFileSync(join(projectDir, 'notes.txt'), 'not a directory\n');
+ const contentDir = join(projectDir, 'notes.txt', 'notes');
+ expect(statSync(dirname(contentDir)).isFile()).toBe(true);
+ writeAt(
+ projectDir,
+ '.ok/local/logs/server-current.jsonl',
+ jsonl([{ level: 30, path: join(contentDir, 'note.md'), msg: 'opened' }]),
+ );
+
+ const collected = await collectBundle({
+ contentDir,
+ projectDir,
+ redact: true,
+ deps: makeDeterministicDeps(),
+ });
+ onTestFinished(() => collected.cleanup());
+
+ expect(readStagedJsonl(collected.stagingDir, 'logs/server-current.jsonl')).toEqual([
+ { level: 30, path: `<CONTENT_DIR>${sep}note.md`, msg: 'opened' },
+ ]);
+ });
+});
+
describe('collectBundle — loss-capture ring', () => {
test('stages the content-loss ring under state/ with its raw doc name intact', async () => {
const contentDir = makeTmpDir();
diff --git a/packages/cli/src/diagnose/bundle.ts b/packages/cli/src/diagnose/bundle.ts
index 27ba3a82d..d177351c3 100644
--- a/packages/cli/src/diagnose/bundle.ts
+++ b/packages/cli/src/diagnose/bundle.ts
@@ -37,7 +37,7 @@ import {
import { redactContent } from '../commands/bug-report-redact.ts';
import { PACKAGE_VERSION } from '../constants.ts';
import { defaultReadLanguage, type LanguageMetadata } from '../report-language.ts';
-import { isRotatedLogPath, redactStagedBundle } from './bundle-redact.ts';
+import { contentDirSpellings, isRotatedLogPath, redactStagedBundle } from './bundle-redact.ts';
import {
type DiagnosticReportCollection,
prepareDiagnosticReportText,
@@ -710,9 +710,11 @@ export async function collectBundle(opts: CollectBundleOpts): Promise<CollectedB
writeFileSync(join(stagingDir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+ const spellings = contentDirSpellings(contentDir);
const contentDirVisible = stagedFiles.some((absPath) => {
try {
- return readFileSync(absPath, 'utf-8').includes(contentDir);
+ const text = readFileSync(absPath, 'utf-8');
+ return spellings.some((spelling) => text.includes(spelling));
} catch {
return false;
}
diff --git a/packages/desktop/tests/smoke/agent-patch-divergence-probe.e2e.ts b/packages/desktop/tests/smoke/agent-patch-divergence-probe.e2e.ts
index d21b40af0..433198044 100644
--- a/packages/desktop/tests/smoke/agent-patch-divergence-probe.e2e.ts
+++ b/packages/desktop/tests/smoke/agent-patch-divergence-probe.e2e.ts
@@ -1,5 +1,6 @@
import { randomUUID } from 'node:crypto';
-import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, realpathSync, writeFileSync } from 'node:fs';
+import { realpath } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
@@ -234,6 +235,7 @@ async function executeRace(opts: {
}),
});
let httpStatus: number;
+ let responseBody: string;
if (randomizedStaggerMs !== undefined && randomizedStaggerMs > 0) {
const firstHalf = humanText.slice(0, 4);
const secondHalf = humanText.slice(4);
@@ -244,13 +246,16 @@ async function executeRace(opts: {
page.keyboard.type(secondHalf, { delay: typingDelay }),
]);
httpStatus = agentRes.status;
+ responseBody = await agentRes.text();
} else {
const [agentRes] = await Promise.all([
agentPatchPromise(),
page.keyboard.type(humanText, { delay: typingDelay }),
]);
httpStatus = agentRes.status;
+ responseBody = await agentRes.text();
}
+ console.log(`[PROBE ${variant} trial ${trial}] response:`, { httpStatus, responseBody });
let finalContent = '';
const readFailures: string[] = [];
@@ -309,6 +314,12 @@ async function setupElectron(
test.skip(!TARGET.exists, TARGET.missingReason);
const contentDir = mkdtempSync(join(tmpdir(), `ok-agent-patch-probe-${variantTag}-`));
+ console.log(`[PROBE ${variantTag}] content root:`, {
+ contentDir,
+ realpathSync: realpathSync(contentDir),
+ realpathSyncNative: realpathSync.native(contentDir),
+ realpathAsync: await realpath(contentDir),
+ });
const userDataDir = mkdtempSync(join(tmpdir(), `ok-pw-userdata-${variantTag}-`));
const docName = `probe-${variantTag}-${randomUUID().slice(0, 8)}`;
const initialContent = SEED_MARKDOWN;
@@ -527,6 +538,7 @@ test.describe('PRD-6666 — agent-patch divergence (production-built Electron)',
trial,
randomizedStaggerMs: stagger,
});
+ expect(result.httpStatus).toBe(200);
outcomes.cherryPresent.push(result.cherryPresent);
outcomes.bananaAbsent.push(result.bananaAbsent);
outcomes.raceFired.push(result.raceFired);
diff --git a/packages/server/src/asset-walk.ts b/packages/server/src/asset-walk.ts
index c04df7f09..5c74c2e52 100644
--- a/packages/server/src/asset-walk.ts
+++ b/packages/server/src/asset-walk.ts
@@ -8,6 +8,7 @@ import {
LINKABLE_ASSET_EXTENSIONS,
} from '@inkeep/open-knowledge-core';
import type { ContentFilter } from './content-filter.ts';
+import { resolveDirectoryRoot } from './directory-root.ts';
import { isSupportedAssetFile } from './doc-extensions.ts';
import { isWithinDir, toPosix } from './path-utils.ts';
@@ -51,7 +52,7 @@ export function seedSingleDirBasenameIndex(opts: {
}
export async function seedBasenameIndex(opts: SeedOptions): Promise<void> {
- const root = opts.contentDir;
+ const root = resolveDirectoryRoot(opts.contentDir, { root: 'content', component: 'asset-walk' });
const visited = new Set<number>();
async function walk(dir: string): Promise<void> {
diff --git a/packages/server/src/directory-root.test.ts b/packages/server/src/directory-root.test.ts
new file mode 100644
index 000000000..44f480e61
--- /dev/null
+++ b/packages/server/src/directory-root.test.ts
@@ -0,0 +1,56 @@
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { resolveDirectoryRoot } from './directory-root.ts';
+import { getLogger } from './logger.ts';
+
+describe('resolveDirectoryRoot', () => {
+ let scratch: string;
+
+ beforeEach(() => {
+ scratch = mkdtempSync(join(tmpdir(), 'ok-directory-root-'));
+ });
+
+ afterEach(() => {
+ vi.restoreAllMocks();
+ rmSync(scratch, { recursive: true, force: true });
+ });
+
+ function diagnosticSpies() {
+ const logger = getLogger('directory-root');
+ const warn = vi.spyOn(logger, 'warn');
+ const debug = vi.spyOn(logger, 'debug');
+ return () => [...warn.mock.calls, ...debug.mock.calls].map(([fields]) => fields);
+ }
+
+ it('returns the native spelling of an existing directory reached through a link, without a diagnostic', () => {
+ const target = join(scratch, 'target');
+ mkdirSync(target);
+ const link = join(scratch, 'link');
+ symlinkSync(target, link, 'dir');
+ const diagnostics = diagnosticSpies();
+
+ const resolved = resolveDirectoryRoot(link, { root: 'content', component: 'asset-walk' });
+
+ expect(resolved).toBe(realpathSync.native(target));
+ expect(diagnostics()).toEqual([]);
+ });
+
+ it('keeps the given path and records which root stayed unresolved, with the errno, when native resolution fails', () => {
+ const file = join(scratch, 'not-a-directory');
+ writeFileSync(file, '');
+ const unresolvable = join(file, 'sub');
+ const diagnostics = diagnosticSpies();
+
+ const resolved = resolveDirectoryRoot(unresolvable, {
+ root: 'project',
+ component: 'persistence',
+ });
+
+ expect(resolved).toBe(unresolvable);
+ expect(diagnostics()).toEqual([
+ expect.objectContaining({ root: 'project', component: 'persistence', code: 'ENOTDIR' }),
+ ]);
+ });
+});
diff --git a/packages/server/src/directory-root.ts b/packages/server/src/directory-root.ts
new file mode 100644
index 000000000..ceac9897c
--- /dev/null
+++ b/packages/server/src/directory-root.ts
@@ -0,0 +1,32 @@
+import { realpathSync } from 'node:fs';
+import { errnoCode } from './http/handler-utils.ts';
+import { getLogger } from './logger.ts';
+
+const log = getLogger('directory-root');
+
+export function resolveNativePath(path: string): string {
+ return realpathSync.native(path);
+}
+
+export function resolveDirectoryRoot(
+ directory: string,
+ site: {
+ root: 'content' | 'project';
+ component:
+ | 'persistence'
+ | 'local-target-index'
+ | 'asset-walk'
+ | 'file-watcher'
+ | 'server-factory';
+ },
+): string {
+ try {
+ return resolveNativePath(directory);
+ } catch (err) {
+ const code = errnoCode(err);
+ const fields = { path: directory, root: site.root, component: site.component, code };
+ if (code === 'ENOENT') log.debug(fields, 'directory root left unresolved');
+ else log.warn(fields, 'directory root left unresolved');
+ return directory;
+ }
+}
diff --git a/packages/server/src/file-watcher-removal-syscall.test.ts b/packages/server/src/file-watcher-removal-syscall.test.ts
index 5160c05b4..584e2396a 100644
--- a/packages/server/src/file-watcher-removal-syscall.test.ts
+++ b/packages/server/src/file-watcher-removal-syscall.test.ts
@@ -7,10 +7,15 @@ import { isSelfRemoval, registerRemoval, removalTracker } from './file-watcher.t
vi.mock('node:fs', async (importOriginal) => {
const fs = await importOriginal<typeof import('node:fs')>();
- return { ...fs, realpathSync: vi.fn(fs.realpathSync) };
+ return {
+ ...fs,
+ realpathSync: Object.assign(vi.fn(fs.realpathSync), {
+ native: vi.fn(fs.realpathSync.native),
+ }),
+ };
});
-const mockedRealpathSync = vi.mocked(realpathSync);
+const mockedRealpathSync = vi.mocked(realpathSync.native);
let removalDir: string;
diff --git a/packages/server/src/file-watcher.ts b/packages/server/src/file-watcher.ts
index 767788723..9ed9d17d1 100644
--- a/packages/server/src/file-watcher.ts
+++ b/packages/server/src/file-watcher.ts
@@ -9,11 +9,12 @@ import {
watch as watchFsPath,
} from 'node:fs';
import { lstat, readdir, readFile, realpath, stat } from 'node:fs/promises';
-import { basename, dirname, extname, join, relative } from 'node:path';
+import { basename, dirname, extname, isAbsolute, join, relative, sep } from 'node:path';
import { LINKABLE_ASSET_EXTENSIONS } from '@inkeep/open-knowledge-core';
import { isConfigDoc, isReservedForUserTree, isSystemDoc } from './cc1-broadcast.ts';
import { type ContentFilter, WATCHER_STRUCTURAL_IGNORE_DIRS } from './content-filter.ts';
import { isWithinContentDir } from './content-path.ts';
+import { resolveDirectoryRoot, resolveNativePath } from './directory-root.ts';
import {
forgetDocExtension,
getDocExtension,
@@ -161,7 +162,11 @@ export function fileIndexEntryMembers(
],
};
}
- const targetPath = toPosix(relative(contentDir, entry.canonicalPath));
+ const targetPath = indexedTargetPath(
+ contentDir,
+ entry.canonicalPath,
+ entry.kind === 'markdown' ? `${name}${extname(entry.canonicalPath)}` : name,
+ );
return {
resolved: false,
members: [
@@ -171,6 +176,16 @@ export function fileIndexEntryMembers(
};
}
+export function indexedTargetPath(
+ contentDir: string,
+ canonicalPath: string,
+ recordedPath: string,
+): string {
+ const rel = toPosix(relative(contentDir, canonicalPath));
+ if (rel === '..' || rel.startsWith('../') || isAbsolute(rel)) return recordedPath;
+ return rel;
+}
+
export interface FolderIndexEntry {
size: 0;
modified: string;
@@ -178,6 +193,24 @@ export interface FolderIndexEntry {
inode: number;
}
+class WatcherFolderIndex extends Map<string, FolderIndexEntry> {
+ readonly #root: string;
+
+ constructor(root: string) {
+ super();
+ this.#root = root;
+ }
+
+ override set(relativePath: string, entry: FolderIndexEntry): this {
+ const spelledUnderRoot =
+ entry.canonicalPath === this.#root || entry.canonicalPath.startsWith(`${this.#root}${sep}`);
+ return super.set(
+ relativePath,
+ spelledUnderRoot ? entry : { ...entry, canonicalPath: declaredPathKey(entry.canonicalPath) },
+ );
+ }
+}
+
function derivePageMeta(
content: string,
docName: string,
@@ -225,24 +258,40 @@ const WRITE_TRACKER_TTL_MS = 10_000;
const REMOVAL_TRACKER_TTL_MS = 30_000;
export function registerWrite(filePath: string, hash: string): void {
- const queue = writeTracker.get(filePath) ?? [];
+ const key = declaredPathKey(filePath);
+ const queue = writeTracker.get(key) ?? [];
queue.push({ hash, timestamp: Date.now() });
- writeTracker.set(filePath, queue);
+ writeTracker.set(key, queue);
}
export const removalTracker = new Map<string, number>();
-function removalKey(filePath: string): string {
+function declaredPathKey(filePath: string): string {
+ const parent = dirname(filePath);
+ if (parent === filePath) return filePath;
try {
- return join(realpathSync(dirname(filePath)), basename(filePath));
+ return join(resolveNativePath(parent), basename(filePath));
} catch (e) {
const code = errnoCode(e);
- if (code !== 'ENOENT') {
- log.warn(
- { path: filePath, code },
- `realpathSync failed for the removal key of ${filePath} (${code})`,
- );
- }
+ if (code === 'ENOENT') return join(declaredPathKey(parent), basename(filePath));
+ log.warn(
+ { path: filePath, code },
+ `native path resolution failed for the declared key of ${filePath} (${code})`,
+ );
+ return filePath;
+ }
+}
+
+function observedPathKey(filePath: string): string {
+ try {
+ return resolveNativePath(filePath);
+ } catch (e) {
+ const code = errnoCode(e);
+ if (code === 'ENOENT') return declaredPathKey(filePath);
+ log.warn(
+ { path: filePath, code },
+ `native path resolution failed for the observed key of ${filePath} (${code})`,
+ );
return filePath;
}
}
@@ -255,7 +304,7 @@ type _RawStringIsNotARemovalDeclaration = Assert<string extends RemovalDeclarati
/* STOP: call this before the unlink, retract it if the unlink throws, and never resolve the
leaf; the watcher reports a removed alias at the alias, not at the target it pointed to. */
export function registerRemoval(filePath: string): RemovalDeclaration {
- const key = removalKey(filePath);
+ const key = declaredPathKey(filePath);
removalTracker.set(key, Date.now());
return key as RemovalDeclaration;
}
@@ -266,7 +315,7 @@ export function retractRemoval(declaration: RemovalDeclaration): void {
function voidRemoval(filePath: string, declaredBeforeBatch: ReadonlySet<string>): void {
if (declaredBeforeBatch.size === 0) return;
- const key = removalKey(filePath);
+ const key = declaredPathKey(filePath);
if (!declaredBeforeBatch.has(key)) return;
removalTracker.delete(key);
}
@@ -274,7 +323,7 @@ function voidRemoval(filePath: string, declaredBeforeBatch: ReadonlySet<string>)
/* STOP: return false on every ambiguous input; a true discards a real disk deletion. */
export function isSelfRemoval(filePath: string): boolean {
if (removalTracker.size === 0) return false;
- const key = removalKey(filePath);
+ const key = declaredPathKey(filePath);
const timestamp = removalTracker.get(key);
if (timestamp === undefined) return false;
removalTracker.delete(key);
@@ -406,7 +455,7 @@ function eventEscapesContentDir(rawPath: string, contentDir: string): boolean {
if (!lst.isSymbolicLink()) return false;
let canonical: string;
try {
- canonical = realpathSync(rawPath);
+ canonical = resolveNativePath(rawPath);
} catch (e) {
const code = errnoCode(e);
if (code !== 'ENOENT' && code !== 'ELOOP') {
@@ -630,7 +679,7 @@ async function classifyEventsInternal(
let canonical: string;
try {
- canonical = realpathSync(rawPath);
+ canonical = resolveNativePath(rawPath);
} catch (e) {
const code = errnoCode(e);
if (code !== 'ENOENT' && code !== 'ELOOP') {
@@ -740,6 +789,17 @@ async function classifyEventsInternal(
return results;
}
+function declaredDiskEvent(event: DiskEvent): DiskEvent {
+ if (event.kind === 'rename') {
+ return {
+ ...event,
+ oldPath: declaredPathKey(event.oldPath),
+ newPath: declaredPathKey(event.newPath),
+ };
+ }
+ return { ...event, path: declaredPathKey(event.path) };
+}
+
export function isSelfWrite(filePath: string, hash: string): boolean {
const queue = writeTracker.get(filePath);
if (!queue) return false;
@@ -1089,7 +1149,7 @@ function registerKnownGeneralPath(
if (relation.path === lexicalName) continue;
const path = join(contentDir, relation.path);
try {
- const actualTarget = realpathSync(path);
+ const actualTarget = resolveNativePath(path);
if (!isWithinContentDir(actualTarget, contentDir)) {
changes.set(relation.path, null);
continue;
@@ -2093,7 +2153,7 @@ function updateFolderIndexFromRawEvents(
folderStat = lst;
} else if (lst.isSymbolicLink()) {
try {
- canonicalPath = realpathSync(raw.path);
+ canonicalPath = resolveNativePath(raw.path);
if (!isWithinContentDir(canonicalPath, contentDir)) continue;
const stat = statSync(canonicalPath);
if (stat.isDirectory()) folderStat = stat;
@@ -2379,34 +2439,12 @@ async function handleRawEventsInternal(
if (event.kind !== 'delete' && event.kind !== 'rename') {
const hash = contentHash(event.content);
- let checkPath = event.path;
- try {
- checkPath = realpathSync(event.path);
- } catch (e) {
- const code = errnoCode(e);
- if (code !== 'ENOENT') {
- log.warn(
- { path: event.path, code },
- `realpathSync failed for self-write check on ${event.path} (${code})`,
- );
- }
- }
+ const checkPath = observedPathKey(event.path);
isSelf = isSelfWrite(checkPath, hash);
voidRemoval(event.path, declaredBeforeBatch);
} else if (event.kind === 'rename') {
const hash = contentHash(event.content);
- let checkPath = event.newPath;
- try {
- checkPath = realpathSync(event.newPath);
- } catch (e) {
- const code = errnoCode(e);
- if (code !== 'ENOENT') {
- log.warn(
- { path: event.newPath, code },
- `realpathSync failed for self-write check on ${event.newPath} (${code})`,
- );
- }
- }
+ const checkPath = observedPathKey(event.newPath);
isSelf = isSelfWrite(checkPath, hash);
indexEvent = { ...event, newPath: checkPath };
voidRemoval(event.oldPath, declaredBeforeBatch);
@@ -2546,10 +2584,10 @@ async function handleRawEventsInternal(
let canonicalPath: string;
let canonicalContentDir: string;
try {
- canonicalContentDir = realpathSync(contentDir);
+ canonicalContentDir = resolveNativePath(contentDir);
st = lstatSync(raw.path);
leafSymlink = st.isSymbolicLink();
- canonicalPath = realpathSync(raw.path);
+ canonicalPath = resolveNativePath(raw.path);
if (leafSymlink) st = statSync(canonicalPath);
} catch (e) {
const code = errnoCode(e);
@@ -3004,7 +3042,7 @@ async function recoverDiskChanges(
try {
const lst = lstatSync(path);
if (lst.isSymbolicLink()) {
- canonicalPath = realpathSync(path);
+ canonicalPath = resolveNativePath(path);
if (!isWithinContentDir(canonicalPath, contentDir)) {
removeFolderIndexEntries(folderIndex, relativePath);
folderAliasIndex.delete(relativePath);
@@ -3443,12 +3481,10 @@ export async function startWatcher(
} = {},
): Promise<WatcherHandle> {
const { onRawBatch, onRecoveryComplete } = opts;
- let contentDir: string;
- try {
- contentDir = realpathSync(contentDirRaw);
- } catch {
- contentDir = contentDirRaw;
- }
+ const contentDir = resolveDirectoryRoot(contentDirRaw, {
+ root: 'content',
+ component: 'file-watcher',
+ });
const fileIndex = new Map<string, FileIndexEntry>();
const generalFileIndex = new GeneralFileIndex(contentDir);
@@ -3458,7 +3494,7 @@ export async function startWatcher(
yield* generalFileIndex;
},
};
- const folderIndex = new Map<string, FolderIndexEntry>();
+ const folderIndex = new WatcherFolderIndex(contentDir);
const aliasMap = new Map<string, string>();
const aliasPaths = new Map<string, string>();
const folderAliasIndex = new Map<string, string>();
@@ -3589,7 +3625,8 @@ export async function startWatcher(
getStructuralIgnoreDirs() {
return structuralIgnoreDirs;
},
- mutateFileIndex(event) {
+ mutateFileIndex(reportedEvent) {
+ const event = declaredDiskEvent(reportedEvent);
if (event.kind === 'rename') {
activePublicMutations?.markdownNames.add(event.oldDocName);
activePublicMutations?.markdownNames.add(event.newDocName);
@@ -3612,7 +3649,7 @@ export async function startWatcher(
const lexicalPath = join(contentDir, event.relativePath);
const lexicalStat = lstatSync(lexicalPath);
const leafSymlink = lexicalStat.isSymbolicLink();
- const canonicalPath = realpathSync(lexicalPath);
+ const canonicalPath = resolveNativePath(lexicalPath);
if (!isWithinContentDir(canonicalPath, contentDir)) {
throw new Error('General file path resolves outside content directory');
}
diff --git a/packages/server/src/http/document-routes.ts b/packages/server/src/http/document-routes.ts
index 47ab4daa3..137f6a8de 100644
--- a/packages/server/src/http/document-routes.ts
+++ b/packages/server/src/http/document-routes.ts
@@ -1,6 +1,6 @@
import { existsSync, readFileSync } from 'node:fs';
import type { IncomingMessage, ServerResponse } from 'node:http';
-import { relative, resolve } from 'node:path';
+import { resolve } from 'node:path';
import type { Document, Hocuspocus } from '@hocuspocus/server';
import {
type DocumentListEntry,
@@ -22,10 +22,10 @@ import {
type FileIndexEntry,
type FolderIndexEntry,
fileIndexEntryMembers,
+ indexedTargetPath,
} from '../file-watcher.ts';
import type { PinoLogger } from '../logger.ts';
import { extractPageIcon, extractPageTitle } from '../page-identity.ts';
-import { toPosix } from '../path-utils.ts';
import type { ApiRouteTable } from './api-pipeline.ts';
import { createStreamingErrorWriter, errorResponse } from './error-response.ts';
import { withValidation } from './request-validation.ts';
@@ -565,7 +565,7 @@ export function createDocumentRoutes(deps: DocumentRouteDeps): DocumentRoutes {
for (const [canonicalPrefix, aliasPrefixes] of aliasesByCanonical) {
const canonRoot = folderIndex.get(canonicalPrefix);
const rootTarget = canonRoot
- ? toPosix(relative(contentDir, canonRoot.canonicalPath))
+ ? indexedTargetPath(contentDir, canonRoot.canonicalPath, canonicalPrefix)
: canonicalPrefix;
for (const aliasPrefix of aliasPrefixes) {
if (!passesDirFilter(aliasPrefix)) continue;
@@ -606,7 +606,7 @@ export function createDocumentRoutes(deps: DocumentRouteDeps): DocumentRoutes {
docExt: '.md',
isSymlink: true,
canonicalDocName: folderPath,
- targetPath: toPosix(relative(contentDir, fEntry.canonicalPath)),
+ targetPath: indexedTargetPath(contentDir, fEntry.canonicalPath, folderPath),
});
});
}
diff --git a/packages/server/src/local-target-index.ts b/packages/server/src/local-target-index.ts
index 41b3af133..61f15a748 100644
--- a/packages/server/src/local-target-index.ts
+++ b/packages/server/src/local-target-index.ts
@@ -1,6 +1,6 @@
-import { type Dirent, existsSync, realpathSync } from 'node:fs';
+import { type Dirent, existsSync } from 'node:fs';
import { readdir, readFile, realpath, stat } from 'node:fs/promises';
-import { isAbsolute, join, relative } from 'node:path';
+import { isAbsolute, join, relative, resolve } from 'node:path';
import {
classifyMarkdownHref,
resolveAssetProjectPath,
@@ -8,6 +8,7 @@ import {
} from '@inkeep/open-knowledge-core';
import { isLinkIndexExcludedDoc } from './cc1-broadcast.ts';
import type { ContentFilter } from './content-filter.ts';
+import { resolveDirectoryRoot } from './directory-root.ts';
import { isSupportedDocFile, stripDocExtension } from './doc-extensions.ts';
import { instrumentIndexRebuild, instrumentIndexUpdate } from './index-telemetry.ts';
import {
@@ -199,11 +200,10 @@ export class LocalTargetIndex {
constructor(options: LocalTargetIndexOptions) {
this.contentDir = options.contentDir;
- try {
- this.canonicalContentDir = realpathSync(options.contentDir);
- } catch {
- this.canonicalContentDir = options.contentDir;
- }
+ this.canonicalContentDir = resolveDirectoryRoot(resolve(options.contentDir), {
+ root: 'content',
+ component: 'local-target-index',
+ });
this.contentFilter = options.contentFilter;
this.readDocument = options.readDocument ?? ((filePath) => readFile(filePath, 'utf-8'));
this.readDirectory = options.readDirectory ?? ((dir) => readdir(dir, { withFileTypes: true }));
diff --git a/packages/server/src/parcel-drop-notice.test.ts b/packages/server/src/parcel-drop-notice.test.ts
index bbd4e771f..ade5b2c76 100644
--- a/packages/server/src/parcel-drop-notice.test.ts
+++ b/packages/server/src/parcel-drop-notice.test.ts
@@ -134,6 +134,13 @@ vi.mock('node:fs', async (importOriginal) => {
admissionFault.observed = true;
throw Object.assign(new Error('directory read denied'), { code: 'EACCES', path });
};
+ const denyRealpath = (path: unknown): void => {
+ fail('realpath', path);
+ if (admissionFault.maskedAncestor && String(path) === admissionFault.maskedAncestor) {
+ admissionFault.observed = true;
+ throw Object.assign(new Error('directory read denied'), { code: 'EACCES', path });
+ }
+ };
return {
...fs,
existsSync: ((...args: Parameters<typeof fs.existsSync>) => {
@@ -160,14 +167,18 @@ vi.mock('node:fs', async (importOriginal) => {
}
return fs.lstatSync(...args);
}) as typeof fs.lstatSync,
- realpathSync: ((...args: Parameters<typeof fs.realpathSync>) => {
- fail('realpath', args[0]);
- if (admissionFault.maskedAncestor && String(args[0]) === admissionFault.maskedAncestor) {
- admissionFault.observed = true;
- throw Object.assign(new Error('directory read denied'), { code: 'EACCES', path: args[0] });
- }
- return fs.realpathSync(...args);
- }) as typeof fs.realpathSync,
+ realpathSync: Object.assign(
+ ((...args: Parameters<typeof fs.realpathSync>) => {
+ denyRealpath(args[0]);
+ return fs.realpathSync(...args);
+ }) as typeof fs.realpathSync,
+ {
+ native: ((...args: Parameters<typeof fs.realpathSync.native>) => {
+ denyRealpath(args[0]);
+ return fs.realpathSync.native(...args);
+ }) as typeof fs.realpathSync.native,
+ },
+ ),
readFileSync: ((...args: Parameters<typeof fs.readFileSync>) => {
fail('read', args[0]);
if (admissionFault.maskedAncestor && String(args[0]) === admissionFault.maskedAncestor) {
diff --git a/packages/server/src/path-identity.test.ts b/packages/server/src/path-identity.test.ts
new file mode 100644
index 000000000..746f7bec0
--- /dev/null
+++ b/packages/server/src/path-identity.test.ts
@@ -0,0 +1,807 @@
+import { randomUUID } from 'node:crypto';
+import {
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ realpathSync,
+ rmSync,
+ symlinkSync,
+ unlinkSync,
+ writeFileSync,
+} from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, relative, sep } from 'node:path';
+import { createBasenameIndex } from '@inkeep/open-knowledge-core';
+import { afterEach, describe, expect, type TestContext, test, vi } from 'vitest';
+import * as Y from 'yjs';
+import { seedBasenameIndex } from './asset-walk.ts';
+import { composeAndWriteRawBody } from './bridge-intake.ts';
+import { bootCompositionRig } from './composition-rig.test-helper.ts';
+import { DocumentDurabilityState } from './document-durability-state.ts';
+import {
+ contentHash,
+ type DiskEvent,
+ getWatcherDecisionRingSnapshot,
+ registerRemoval,
+ registerWrite,
+ resetWatcherDecisionDiagnostics,
+ startWatcher,
+} from './file-watcher.ts';
+import { LocalTargetIndex } from './local-target-index.ts';
+import { createPersistenceExtension } from './persistence.ts';
+import { createServer, type ServerInstance } from './server-factory.ts';
+import { destroyShadowRepo, initShadowRepo, shadowGit } from './shadow-repo.ts';
+import { readSkillPlacements } from './skill-placements.ts';
+import { waitWithinTestBudget } from './wait-within-test-budget.test-helper.ts';
+
+const echoGate = vi.hoisted(() => ({
+ docName: null as string | null,
+ held: [] as Array<() => Promise<void>>,
+}));
+
+vi.mock('./file-watcher.ts', async (importOriginal) => {
+ const actual = await importOriginal<typeof import('./file-watcher.ts')>();
+ return {
+ ...actual,
+ startWatcher: (...[contentDir, onDiskEvent, ...rest]: Parameters<typeof actual.startWatcher>) =>
+ actual.startWatcher(
+ contentDir,
+ async (event) => {
+ if (event.kind === 'update' && event.docName === echoGate.docName) {
+ echoGate.held.push(() => onDiskEvent(event));
+ return;
+ }
+ await onDiskEvent(event);
+ },
+ ...rest,
+ ),
+ };
+});
+
+const fixtures: string[] = [];
+
+afterEach(() => {
+ for (const fixture of fixtures.splice(0)) rmSync(fixture, { recursive: true, force: true });
+});
+
+const ROOT_SPELLINGS = ['natively spelled', 'symlinked', 'case-aliased', '8.3 short-name'] as const;
+type RootSpelling = (typeof ROOT_SPELLINGS)[number];
+
+interface SpelledRoot {
+ spelling: RootSpelling;
+ projectDir: string;
+ contentDir: string;
+ canonicalContentDir: string;
+}
+
+function spelledRoot(spelling: RootSpelling): SpelledRoot {
+ const temporaryDir = mkdtempSync(join(tmpdir(), 'ok-path-identity-'));
+ fixtures.push(temporaryDir);
+ const projectDir =
+ spelling === '8.3 short-name' ? temporaryDir : realpathSync.native(temporaryDir);
+ const createdDir = join(projectDir, 'ContentCase');
+ mkdirSync(createdDir);
+ const canonicalContentDir = realpathSync.native(createdDir);
+ switch (spelling) {
+ case 'symlinked': {
+ const contentDir = join(projectDir, 'content-link');
+ symlinkSync(canonicalContentDir, contentDir, 'junction');
+ return { spelling, projectDir, contentDir, canonicalContentDir };
+ }
+ case 'case-aliased':
+ return {
+ spelling,
+ projectDir,
+ contentDir: join(projectDir, 'contentcase'),
+ canonicalContentDir,
+ };
+ default:
+ return { spelling, projectDir, contentDir: createdDir, canonicalContentDir };
+ }
+}
+
+function aliasOwedOnThisLeg(spelling: RootSpelling): boolean {
+ if (process.env.RUNNER_ENVIRONMENT !== 'github-hosted') return false;
+ if (spelling === '8.3 short-name') return process.platform === 'win32';
+ return process.platform === 'darwin' || process.platform === 'win32';
+}
+
+function skipWhereAliasIsAbsent(
+ ctx: TestContext,
+ spelling: RootSpelling,
+ absent: boolean,
+ reason: string,
+): void {
+ expect(
+ absent && aliasOwedOnThisLeg(spelling),
+ `GitHub-hosted ${process.platform} runners produce the ${spelling} spelling, so this leg fails instead of skipping: ${reason}`,
+ ).toBe(false);
+ ctx.skip(absent, reason);
+}
+
+function requireSpellingOnThisLeg(root: SpelledRoot, ctx: TestContext): void {
+ const { spelling, contentDir, canonicalContentDir } = root;
+ switch (spelling) {
+ case 'natively spelled':
+ expect(contentDir).toBe(canonicalContentDir);
+ break;
+ case 'symlinked':
+ ctx.skip(
+ contentDir === realpathSync.native(contentDir),
+ 'native resolution leaves the directory link spelling unchanged on this leg',
+ );
+ break;
+ case 'case-aliased':
+ skipWhereAliasIsAbsent(
+ ctx,
+ spelling,
+ !existsSync(contentDir),
+ 'this filesystem is case-sensitive, so the case alias names no directory',
+ );
+ skipWhereAliasIsAbsent(
+ ctx,
+ spelling,
+ realpathSync(contentDir) === realpathSync.native(contentDir),
+ 'legacy and native resolution agree on this leg: native resolution does not restore the letter case',
+ );
+ break;
+ case '8.3 short-name':
+ skipWhereAliasIsAbsent(
+ ctx,
+ spelling,
+ realpathSync(contentDir) === realpathSync.native(contentDir),
+ 'legacy and native resolution agree on this leg: the temp root has no 8.3 short-name spelling',
+ );
+ break;
+ }
+ expect(realpathSync.native(contentDir)).toBe(canonicalContentDir);
+}
+
+describe('directory identity across server components', () => {
+ test.for(ROOT_SPELLINGS)(
+ 'persistence stores an edited document from the %s root',
+ async (spelling, ctx) => {
+ const root = spelledRoot(spelling);
+ requireSpellingOnThisLeg(root, ctx);
+ const { projectDir, contentDir } = root;
+ const docName = 'note';
+ const seed = '# Note\n\nBefore.\n';
+ const edited = '# Note\n\nAfter.\n';
+ writeFileSync(join(contentDir, `${docName}.md`), seed);
+ const state = new DocumentDurabilityState();
+ const persistence = createPersistenceExtension({
+ contentDir,
+ projectDir,
+ gitEnabled: false,
+ durabilityState: state,
+ });
+ const doc = new Y.Doc();
+ try {
+ composeAndWriteRawBody(doc, edited, 'agent');
+ state.setReconciledBase(docName, seed);
+ state.markAgentWriteStore(docName);
+ await expect(persistence.forceStore(doc, docName)).resolves.toBeUndefined();
+ expect(readFileSync(join(contentDir, `${docName}.md`), 'utf8')).toBe(edited);
+ expect(state.takeStoreFailure(docName)).toBeNull();
+ } finally {
+ doc.destroy();
+ }
+ },
+ );
+
+ test.each([
+ { spelling: 'working directory', contentDir: process.cwd() },
+ { spelling: 'empty', contentDir: '' },
+ ])(
+ 'persistence keeps writes within the $spelling root, which resolves to the working directory',
+ async ({ contentDir }) => {
+ const insideDir = mkdtempSync(join(process.cwd(), 'ok-cwd-root-'));
+ fixtures.push(insideDir);
+ const { projectDir } = spelledRoot('natively spelled');
+ const insidePath = join(insideDir, 'inside.md');
+ const insideName = relative(process.cwd(), insidePath).split(sep).join('/');
+ const outsidePath = join(projectDir, 'outside.md');
+ const seed = '# Note\n\nBefore.\n';
+ const edited = '# Note\n\nAfter.\n';
+ writeFileSync(insidePath, seed);
+ writeFileSync(outsidePath, seed);
+ const state = new DocumentDurabilityState();
+ const persistence = createPersistenceExtension({
+ contentDir,
+ projectDir,
+ gitEnabled: false,
+ durabilityState: state,
+ });
+ const doc = new Y.Doc();
+ try {
+ composeAndWriteRawBody(doc, edited, 'agent');
+ state.setReconciledBase(insideName, seed);
+ state.markAgentWriteStore(insideName);
+ await expect(persistence.forceStore(doc, insideName)).resolves.toBeUndefined();
+ expect(readFileSync(insidePath, 'utf8')).toBe(edited);
+ state.setReconciledBase(outsidePath, seed);
+ state.markAgentWriteStore(outsidePath);
+ await expect(persistence.forceStore(doc, outsidePath)).rejects.toThrow(
+ 'Invalid document name',
+ );
+ expect(readFileSync(outsidePath, 'utf8')).toBe(seed);
+ } finally {
+ doc.destroy();
+ }
+ },
+ );
+
+ test.for(ROOT_SPELLINGS)(
+ 'persistence records edited bytes from the %s project root',
+ async (spelling, ctx) => {
+ const root = spelledRoot(spelling);
+ requireSpellingOnThisLeg(root, ctx);
+ const { contentDir: projectDir, canonicalContentDir: contentDir } = root;
+ const docName = 'note';
+ const seed = '# Note\n\nBefore.\n';
+ const edited = '# Note\n\nAfter.\n';
+ writeFileSync(join(contentDir, `${docName}.md`), seed);
+ const shadow = await initShadowRepo(projectDir);
+ const state = new DocumentDurabilityState();
+ const persistence = createPersistenceExtension({
+ contentDir,
+ projectDir,
+ gitEnabled: true,
+ shadowRef: { current: shadow },
+ durabilityState: state,
+ });
+ const doc = new Y.Doc();
+ try {
+ composeAndWriteRawBody(doc, edited, 'agent');
+ state.setReconciledBase(docName, seed);
+ state.markAgentWriteStore(docName);
+ await expect(persistence.forceStore(doc, docName)).resolves.toBeUndefined();
+ expect(readFileSync(join(contentDir, `${docName}.md`), 'utf8')).toBe(edited);
+ await persistence.flushPendingGitCommit();
+ const git = shadowGit(shadow);
+ const refs = (await git.raw('for-each-ref', '--format=%(objectname)', 'refs/wip/main'))
+ .split('\n')
+ .map((line) => line.trim())
+ .filter(Boolean);
+ expect(refs).not.toEqual([]);
+ await expect(git.raw('show', `${refs[0]}:${docName}.md`)).resolves.toBe(edited);
+ } finally {
+ try {
+ await persistence.flushPendingGitCommit();
+ } finally {
+ doc.destroy();
+ destroyShadowRepo(shadow);
+ }
+ }
+ },
+ );
+
+ test.for(ROOT_SPELLINGS)(
+ 'file target reconciliation finds an existing file from the %s root',
+ async (spelling, ctx) => {
+ const root = spelledRoot(spelling);
+ requireSpellingOnThisLeg(root, ctx);
+ const { contentDir } = root;
+ writeFileSync(join(contentDir, 'target.png'), 'owned asset');
+ const index = new LocalTargetIndex({ contentDir });
+ try {
+ index.setSource('note', '![Image](target.png)\n');
+ expect(index.getAssessments('note')[0]).toMatchObject({
+ resolvedTarget: 'target.png',
+ status: 'missing',
+ });
+ await index.reconcileDependentFileTargetsFromDisk();
+ expect(index.getAssessments('note')[0]).toMatchObject({
+ resolvedTarget: 'target.png',
+ status: 'exact',
+ });
+ } finally {
+ index.close();
+ }
+ },
+ );
+
+ test('file target reconciliation leaves an out-of-root target missing', async () => {
+ const { projectDir, contentDir } = spelledRoot('natively spelled');
+ writeFileSync(join(projectDir, 'outside.png'), 'outside asset');
+ symlinkSync('../outside.png', join(contentDir, 'outside.png'));
+ expect(existsSync(join(contentDir, 'outside.png'))).toBe(true);
+ const index = new LocalTargetIndex({ contentDir });
+ try {
+ index.setSource('note', '![Image](outside.png)\n');
+ await index.reconcileDependentFileTargetsFromDisk();
+ expect(index.getAssessments('note')[0]).toMatchObject({
+ resolvedTarget: 'outside.png',
+ status: 'missing',
+ });
+ } finally {
+ index.close();
+ }
+ });
+
+ test.for(ROOT_SPELLINGS)(
+ 'asset walk includes an in-root file alias from the %s root',
+ async (spelling, ctx) => {
+ const root = spelledRoot(spelling);
+ requireSpellingOnThisLeg(root, ctx);
+ const { contentDir } = root;
+ writeFileSync(join(contentDir, 'target.png'), 'owned asset');
+ symlinkSync('target.png', join(contentDir, 'alias.png'));
+ const index = createBasenameIndex();
+ await seedBasenameIndex({ contentDir, basenameIndex: index });
+ expect(index.resolveEmbed('target.png', 'note.md')).toBe('target.png');
+ expect(index.resolveEmbed('alias.png', 'note.md')).toBe('alias.png');
+ },
+ );
+
+ test.each([
+ { spelling: 'existing', input: '.' },
+ { spelling: 'empty', input: '' },
+ { spelling: 'unresolved', input: `missing${sep}..` },
+ ])('asset walk respects filesystem admission for the $spelling root', async ({ input }) => {
+ const { contentDir } = spelledRoot('natively spelled');
+ writeFileSync(join(contentDir, 'target.png'), 'owned asset');
+ const previousCwd = process.cwd();
+ process.chdir(contentDir);
+ try {
+ const entries = await readdir(input).catch((): string[] => []);
+ const expected = entries.includes('target.png') ? 'target.png' : null;
+ const index = createBasenameIndex();
+ await seedBasenameIndex({ contentDir: input, basenameIndex: index });
+ expect(index.resolveEmbed('target.png', 'note.md')).toBe(expected);
+ } finally {
+ process.chdir(previousCwd);
+ }
+ });
+});
+
+type DirectConnection = Awaited<ReturnType<ServerInstance['hocuspocus']['openDirectConnection']>>;
+
+async function appendParagraph(connection: DirectConnection, text: string): Promise<void> {
+ await connection.transact((doc) => {
+ const paragraph = new Y.XmlElement('paragraph');
+ paragraph.insert(0, [new Y.XmlText(text)]);
+ const fragment = doc.getXmlFragment('default');
+ fragment.insert(fragment.length, [paragraph]);
+ });
+}
+
+async function storeNow(server: ServerInstance, docName: string): Promise<void> {
+ const debounceId = `onStoreDocument-${docName}`;
+ await vi.waitFor(() => expect(server.hocuspocus.debouncer.isDebounced(debounceId)).toBe(true));
+ await server.hocuspocus.debouncer.executeNow(debounceId);
+}
+
+function watcherDecisionsFor(fileName: string): string[] {
+ return getWatcherDecisionRingSnapshot()
+ .filter((record) => record.path.endsWith(`${sep}${fileName}`))
+ .map((record) => record.decision);
+}
+
+async function untilWatcherReportsChanges(contentDir: string): Promise<void> {
+ const probeName = `armed-${randomUUID().slice(0, 8)}.md`;
+ await waitWithinTestBudget(
+ `a watcher decision for ${probeName} under ${contentDir}`,
+ () => {
+ if (watcherDecisionsFor(probeName).length > 0) return true;
+ writeFileSync(join(contentDir, probeName), `# Armed\n\n${randomUUID()}\n`);
+ return false;
+ },
+ { timeoutMs: Number.POSITIVE_INFINITY },
+ );
+}
+
+const WATCHED_ROOT_ROWS = ROOT_SPELLINGS.flatMap((spelling) =>
+ (['chokidar', 'default'] as const).map((watcher) => [spelling, watcher] as const),
+);
+
+function watcherOptions(backend: (typeof WATCHED_ROOT_ROWS)[number][1]) {
+ return backend === 'chokidar' ? { forceBackend: 'chokidar' as const } : {};
+}
+
+interface ListedEntry {
+ kind: string;
+ docName?: string;
+ path?: string;
+ isSymlink?: boolean;
+ canonicalDocName?: string | null;
+ targetPath?: string | null;
+}
+
+async function documentListingFrom(contentDir: string): Promise<ListedEntry[]> {
+ const server = await bootCompositionRig(contentDir);
+ try {
+ await server.ready;
+ const response = await fetch(`http://127.0.0.1:${server.port}/api/documents`);
+ expect(response.status).toBe(200);
+ return ((await response.json()) as { documents: ListedEntry[] }).documents;
+ } finally {
+ await server.destroy();
+ }
+}
+
+describe('one directory identity for watcher keys and linked documents', () => {
+ test.for(WATCHED_ROOT_ROWS)(
+ 'a save from the %s root is suppressed by the %s watcher, and its late echo keeps the newer content',
+ async ([spelling, watcher], ctx) => {
+ const root = spelledRoot(spelling);
+ requireSpellingOnThisLeg(root, ctx);
+ const { contentDir } = root;
+ const home = mkdtempSync(join(tmpdir(), 'ok-path-identity-home-'));
+ fixtures.push(home);
+ const docName = `echo-${randomUUID().slice(0, 8)}`;
+ const filePath = join(contentDir, `${docName}.md`);
+ const seed = '# Echo\n\nSeed paragraph.\n';
+ writeFileSync(filePath, seed);
+ if (watcher === 'chokidar') vi.stubEnv('OK_FILE_WATCHER_BACKEND', 'chokidar');
+ resetWatcherDecisionDiagnostics();
+ echoGate.docName = docName;
+ const server = createServer({
+ contentDir,
+ quiet: true,
+ debounce: 60_000,
+ maxDebounce: 120_000,
+ gitEnabled: false,
+ configHomedirOverride: home,
+ skipStateManifestCheck: true,
+ });
+ try {
+ await server.ready;
+ await untilWatcherReportsChanges(contentDir);
+ const connection = await server.hocuspocus.openDirectConnection(docName);
+ try {
+ const liveSource = () =>
+ server.hocuspocus.documents.get(docName)?.getText('source').toString();
+ await vi.waitFor(() =>
+ expect(server.durabilityState.getReconciledBase(docName)).toBe(seed),
+ );
+ await appendParagraph(connection, 'Alpha edit paragraph.');
+ await storeNow(server, docName);
+ expect(readFileSync(filePath, 'utf8')).toContain('Alpha edit paragraph.');
+ await vi.waitFor(() =>
+ expect(watcherDecisionsFor(`${docName}.md`).length).toBeGreaterThanOrEqual(1),
+ );
+ await appendParagraph(connection, 'Bravo edit paragraph.');
+ await storeNow(server, docName);
+ const newer = readFileSync(filePath, 'utf8');
+ expect(newer).toContain('Bravo edit paragraph.');
+ await vi.waitFor(() =>
+ expect(watcherDecisionsFor(`${docName}.md`).length).toBeGreaterThanOrEqual(2),
+ );
+ for (const deliver of echoGate.held.splice(0).reverse()) await deliver();
+ expect(liveSource()).toBe(newer);
+ expect(server.durabilityState.getReconciledBase(docName)).toBe(newer);
+ expect(watcherDecisionsFor(`${docName}.md`)).toContain('self-write-skip');
+ } finally {
+ await connection.disconnect();
+ }
+ } finally {
+ echoGate.docName = null;
+ echoGate.held.length = 0;
+ vi.unstubAllEnvs();
+ await server.destroy();
+ }
+ },
+ );
+
+ test.for(['natively spelled', 'case-aliased', '8.3 short-name'] as const)(
+ 'a write registered under the %s root before it lands is suppressed by the chokidar watcher',
+ async (spelling, ctx) => {
+ const root = spelledRoot(spelling);
+ requireSpellingOnThisLeg(root, ctx);
+ const fileName = `raw-${randomUUID().slice(0, 8)}.md`;
+ const filePath = join(root.contentDir, fileName);
+ writeFileSync(filePath, '# Raw\n\nBefore.\n');
+ const watcher = await startWatcher(root.contentDir, async () => {}, undefined, {
+ forceBackend: 'chokidar',
+ });
+ try {
+ resetWatcherDecisionDiagnostics();
+ const written = '# Raw\n\nAfter.\n';
+ registerWrite(filePath, contentHash(written));
+ writeFileSync(filePath, written);
+ await vi.waitFor(() => expect(watcherDecisionsFor(fileName)).not.toEqual([]));
+ expect(watcherDecisionsFor(fileName)).toContain('self-write-skip');
+ } finally {
+ await watcher.unsubscribe();
+ }
+ },
+ );
+
+ test.for(['natively spelled', 'case-aliased', '8.3 short-name'] as const)(
+ 'a write registered under the %s root before its file exists is suppressed by the chokidar watcher',
+ async (spelling, ctx) => {
+ const root = spelledRoot(spelling);
+ requireSpellingOnThisLeg(root, ctx);
+ const fileName = `fresh-${randomUUID().slice(0, 8)}.md`;
+ const filePath = join(root.contentDir, fileName);
+ const watcher = await startWatcher(root.contentDir, async () => {}, undefined, {
+ forceBackend: 'chokidar',
+ });
+ try {
+ resetWatcherDecisionDiagnostics();
+ const written = '# Fresh\n\nWritten after its registration.\n';
+ expect(existsSync(filePath)).toBe(false);
+ registerWrite(filePath, contentHash(written));
+ writeFileSync(filePath, written);
+ await vi.waitFor(() => expect(watcherDecisionsFor(fileName)).not.toEqual([]));
+ expect(watcherDecisionsFor(fileName)).toContain('self-write-skip');
+ } finally {
+ await watcher.unsubscribe();
+ }
+ },
+ );
+
+ test.for(ROOT_SPELLINGS)(
+ 'a removal declared under the %s root before the unlink is suppressed by the chokidar watcher',
+ async (spelling, ctx) => {
+ const root = spelledRoot(spelling);
+ requireSpellingOnThisLeg(root, ctx);
+ const fileName = `gone-${randomUUID().slice(0, 8)}.md`;
+ const filePath = join(root.contentDir, fileName);
+ writeFileSync(filePath, '# Gone\n');
+ const watcher = await startWatcher(root.contentDir, async () => {}, undefined, {
+ forceBackend: 'chokidar',
+ });
+ try {
+ resetWatcherDecisionDiagnostics();
+ registerRemoval(filePath);
+ unlinkSync(filePath);
+ await vi.waitFor(() => expect(watcherDecisionsFor(fileName)).not.toEqual([]));
+ expect(watcherDecisionsFor(fileName)).toContain('self-removal-skip');
+ } finally {
+ await watcher.unsubscribe();
+ }
+ },
+ );
+
+ test.for(ROOT_SPELLINGS)(
+ 'links spelled through the %s root or its native spelling load and store, while links out of the root or into private state stay refused',
+ async (spelling, ctx) => {
+ const root = spelledRoot(spelling);
+ requireSpellingOnThisLeg(root, ctx);
+ const { projectDir, contentDir, canonicalContentDir } = root;
+ const original = '# Target\n\nTarget body.\n';
+ const edited = '# Target\n\nTarget body.\n\nAppended.\n';
+ mkdirSync(join(canonicalContentDir, '.ok', 'local'), { recursive: true });
+ const targets = {
+ 'root-spelled': join(contentDir, 'root-target.md'),
+ 'native-spelled': join(canonicalContentDir, 'native-target.md'),
+ outside: join(projectDir, 'outside-target.md'),
+ private: join(contentDir, '.ok', 'local', 'private-target.md'),
+ };
+ for (const [docName, target] of Object.entries(targets)) {
+ writeFileSync(target, original);
+ symlinkSync(target, join(canonicalContentDir, `${docName}.md`));
+ }
+ const loader = createPersistenceExtension({
+ contentDir,
+ projectDir,
+ gitEnabled: false,
+ durabilityState: new DocumentDurabilityState(),
+ });
+ const storeState = new DocumentDurabilityState();
+ const storer = createPersistenceExtension({
+ contentDir,
+ projectDir,
+ gitEnabled: false,
+ durabilityState: storeState,
+ });
+ const load = async (documentName: string): Promise<string> => {
+ const document = new Y.Doc();
+ try {
+ await loader.extension.onLoadDocument?.({
+ document,
+ documentName,
+ context: {},
+ } as never);
+ return document.getText('source').toString();
+ } finally {
+ document.destroy();
+ }
+ };
+ const store = async (documentName: string): Promise<void> => {
+ const document = new Y.Doc();
+ try {
+ composeAndWriteRawBody(document, edited, 'agent');
+ storeState.markAgentWriteStore(documentName);
+ await storer.forceStore(document, documentName);
+ } finally {
+ document.destroy();
+ }
+ };
+ expect(await load('root-spelled')).toBe(original);
+ expect(await load('native-spelled')).toBe(original);
+ expect(await load('outside')).toBe('');
+ expect(await load('private')).toBe('');
+ await expect(store('root-spelled')).resolves.toBeUndefined();
+ await expect(store('native-spelled')).resolves.toBeUndefined();
+ await expect(store('outside')).rejects.toThrow();
+ await expect(store('private')).rejects.toThrow();
+ expect(readFileSync(targets['root-spelled'], 'utf8')).toBe(edited);
+ expect(readFileSync(targets['native-spelled'], 'utf8')).toBe(edited);
+ expect(readFileSync(targets.outside, 'utf8')).toBe(original);
+ expect(readFileSync(targets.private, 'utf8')).toBe(original);
+ },
+ );
+
+ test.for(WATCHED_ROOT_ROWS)(
+ 'a page created under the %s root and deleted on disk is reported deleted under its own name by the %s watcher',
+ async ([spelling, backend], ctx) => {
+ const root = spelledRoot(spelling);
+ requireSpellingOnThisLeg(root, ctx);
+ const docName = `page-${randomUUID().slice(0, 8)}`;
+ const fileName = `${docName}.md`;
+ const fullPath = join(root.contentDir, fileName);
+ const content = '# Page\n\nCreated through the server.\n';
+ const events: DiskEvent[] = [];
+ const watcher = await startWatcher(
+ root.contentDir,
+ async (event) => {
+ events.push(event);
+ },
+ undefined,
+ watcherOptions(backend),
+ );
+ try {
+ await untilWatcherReportsChanges(root.contentDir);
+ resetWatcherDecisionDiagnostics();
+ writeFileSync(fullPath, content, { flag: 'wx' });
+ registerWrite(fullPath, contentHash(content));
+ watcher.mutateFileIndex({ kind: 'create', path: fullPath, docName, content });
+ await vi.waitFor(() => expect(watcherDecisionsFor(fileName)).not.toEqual([]));
+ unlinkSync(fullPath);
+ await vi.waitFor(() =>
+ expect(events).toContainEqual(expect.objectContaining({ kind: 'delete', docName })),
+ );
+ expect(watcher.getFileIndex().has(docName)).toBe(false);
+ } finally {
+ await watcher.unsubscribe();
+ }
+ },
+ );
+
+ test.for(WATCHED_ROOT_ROWS)(
+ 'links created under the %s root through its own spelling or its native spelling are aliases of their target for the %s watcher',
+ async ([spelling, backend], ctx) => {
+ const root = spelledRoot(spelling);
+ requireSpellingOnThisLeg(root, ctx);
+ writeFileSync(join(root.canonicalContentDir, 'target.md'), '# Target\n\nTarget body.\n');
+ const watcher = await startWatcher(
+ root.contentDir,
+ async () => {},
+ undefined,
+ watcherOptions(backend),
+ );
+ try {
+ await untilWatcherReportsChanges(root.contentDir);
+ resetWatcherDecisionDiagnostics();
+ symlinkSync(
+ join(root.canonicalContentDir, 'target.md'),
+ join(root.canonicalContentDir, 'link-native.md'),
+ );
+ symlinkSync(
+ join(root.contentDir, 'target.md'),
+ join(root.canonicalContentDir, 'link-root.md'),
+ );
+ await vi.waitFor(() => {
+ expect(watcherDecisionsFor('link-native.md')).not.toEqual([]);
+ expect(watcherDecisionsFor('link-root.md')).not.toEqual([]);
+ });
+ expect(Object.fromEntries(watcher.getAliasMap())).toEqual({
+ 'link-native': 'target',
+ 'link-root': 'target',
+ });
+ } finally {
+ await watcher.unsubscribe();
+ }
+ },
+ );
+
+ test.for(WATCHED_ROOT_ROWS)(
+ 'an in-place skill edited under the %s root refreshes its recorded copy with the %s watcher',
+ async ([spelling, watcher], ctx) => {
+ const root = spelledRoot(spelling);
+ requireSpellingOnThisLeg(root, ctx);
+ const { contentDir } = root;
+ const home = mkdtempSync(join(tmpdir(), 'ok-path-identity-home-'));
+ fixtures.push(home);
+ const skillName = 'alias-refresh';
+ const skillFile = (body: string) =>
+ `---\nname: ${skillName}\ndescription: Keeps its recorded copies current.\n---\n\n${body}\n`;
+ const canonicalSkill = join('.agents', 'skills', skillName, 'SKILL.md');
+ const copiedSkill = join('.claude', 'skills', skillName, 'SKILL.md');
+ for (const skill of [canonicalSkill, copiedSkill]) {
+ mkdirSync(join(root.canonicalContentDir, skill, '..'), { recursive: true });
+ writeFileSync(join(root.canonicalContentDir, skill), skillFile('Before the edit.'));
+ }
+ if (watcher === 'chokidar') vi.stubEnv('OK_FILE_WATCHER_BACKEND', 'chokidar');
+ const server = createServer({
+ contentDir,
+ quiet: true,
+ gitEnabled: false,
+ configHomedirOverride: home,
+ skipStateManifestCheck: true,
+ });
+ try {
+ await server.ready;
+ await untilWatcherReportsChanges(contentDir);
+ await vi.waitFor(() =>
+ expect(readSkillPlacements(contentDir)[skillName]?.map((p) => p.path)).toEqual([
+ `.claude/skills/${skillName}`,
+ ]),
+ );
+ resetWatcherDecisionDiagnostics();
+ const edited = skillFile('After the edit.');
+ writeFileSync(join(root.canonicalContentDir, canonicalSkill), edited);
+ await vi.waitFor(() =>
+ expect(watcherDecisionsFor(join(skillName, 'SKILL.md'))).not.toEqual([]),
+ );
+ await vi.waitFor(() =>
+ expect(readFileSync(join(root.canonicalContentDir, copiedSkill), 'utf8')).toBe(edited),
+ );
+ } finally {
+ vi.unstubAllEnvs();
+ await server.destroy();
+ }
+ },
+ );
+
+ test.for(ROOT_SPELLINGS)(
+ 'the document listing from the %s root labels a linked document by its in-root target',
+ async (spelling, ctx) => {
+ const root = spelledRoot(spelling);
+ requireSpellingOnThisLeg(root, ctx);
+ writeFileSync(join(root.canonicalContentDir, 'target.md'), '# Target\n');
+ symlinkSync('target.md', join(root.canonicalContentDir, 'link.md'));
+ expect(await documentListingFrom(root.contentDir)).toContainEqual(
+ expect.objectContaining({
+ kind: 'document',
+ docName: 'link',
+ isSymlink: true,
+ canonicalDocName: 'target',
+ targetPath: 'target.md',
+ }),
+ );
+ },
+ );
+
+ test.for(ROOT_SPELLINGS)(
+ 'the document listing from the %s root labels a linked folder and what lies beneath it by their in-root targets',
+ async (spelling, ctx) => {
+ const root = spelledRoot(spelling);
+ requireSpellingOnThisLeg(root, ctx);
+ mkdirSync(join(root.canonicalContentDir, 'real', 'sub'), { recursive: true });
+ writeFileSync(join(root.canonicalContentDir, 'real', 'note.md'), '# Note\n');
+ symlinkSync('real', join(root.canonicalContentDir, 'alias'), 'junction');
+ const listing = await documentListingFrom(root.contentDir);
+ expect(listing).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ kind: 'folder',
+ path: 'alias',
+ isSymlink: true,
+ canonicalDocName: 'real',
+ targetPath: 'real',
+ }),
+ expect.objectContaining({
+ kind: 'folder',
+ path: 'alias/sub',
+ isSymlink: true,
+ canonicalDocName: 'real/sub',
+ targetPath: 'real/sub',
+ }),
+ expect.objectContaining({
+ kind: 'document',
+ docName: 'alias/note',
+ isSymlink: true,
+ canonicalDocName: 'real/note',
+ targetPath: 'real/note.md',
+ }),
+ ]),
+ );
+ },
+ );
+});
diff --git a/packages/server/src/persistence.ts b/packages/server/src/persistence.ts
index 73e0d58d9..6f325549f 100644
--- a/packages/server/src/persistence.ts
+++ b/packages/server/src/persistence.ts
@@ -55,6 +55,7 @@ import {
swapContributors,
} from './contributor-tracker.ts';
import type { DerivedDocumentIndexPersistencePort } from './derived-document-index.ts';
+import { resolveDirectoryRoot, resolveNativePath } from './directory-root.ts';
import { applyDiskContentToDoc, FILE_WATCHER_ORIGIN } from './disk-content-intake.ts';
import {
assertNeverStorePublishOutcome,
@@ -390,14 +391,14 @@ export interface PersistenceHandle {
export function createPersistenceExtension(options?: PersistenceOptions): PersistenceHandle {
const durabilityState = options?.durabilityState ?? new DocumentDurabilityState();
- const contentDirRaw = options?.contentDir ?? process.cwd();
- let contentDir: string;
- try {
- contentDir = realpathSync(contentDirRaw);
- } catch {
- contentDir = contentDirRaw;
- }
- const projectDir = options?.projectDir ?? process.cwd();
+ const contentDir = resolveDirectoryRoot(resolve(options?.contentDir ?? process.cwd()), {
+ root: 'content',
+ component: 'persistence',
+ });
+ const projectDir = resolveDirectoryRoot(resolve(options?.projectDir ?? process.cwd()), {
+ root: 'project',
+ component: 'persistence',
+ });
const shadowRef = options?.shadowRef;
const contentRoot = options?.contentRoot || toPosix(relative(projectDir, contentDir)) || '.';
const derivedDocumentIndex = options?.derivedDocumentIndex;
@@ -922,7 +923,7 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
if (!existsSync(requestedDiskPath)) return { kind: 'missing' };
let canonical: string | null = null;
try {
- canonical = realpathSync(requestedDiskPath);
+ canonical = resolveNativePath(requestedDiskPath);
} catch (realpathErr) {
log.warn(
{ err: realpathErr, documentName },
@@ -2033,20 +2034,9 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
if (!existsSync(filePath)) return;
docsWithFileObservedOnDisk.add(documentName);
- let canonical = filePath;
+ let canonical: string;
try {
- const resolvedCanonical = realpathSync(filePath);
- if (
- !isWithinContentDir(resolvedCanonical, contentDir) ||
- resolvesIntoPrivateState(filePath, resolvedCanonical, contentDir)
- ) {
- log.warn(
- { path: filePath, canonical: resolvedCanonical },
- `[persistence] symlink-escape on load: ${filePath} → ${resolvedCanonical}, refusing`,
- );
- return;
- }
- canonical = resolvedCanonical;
+ canonical = resolveNativePath(filePath);
} catch (e) {
const code = errnoCode(e);
if (code === 'ELOOP') {
@@ -2056,6 +2046,21 @@ export function createPersistenceExtension(options?: PersistenceOptions): Persis
);
return;
}
+ log.warn(
+ { path: filePath, code },
+ `[persistence] Could not resolve ${filePath} on load (${code}), refusing`,
+ );
+ return;
+ }
+ if (
+ !isWithinContentDir(canonical, contentDir) ||
+ resolvesIntoPrivateState(filePath, canonical, contentDir)
+ ) {
+ log.warn(
+ { path: filePath, canonical },
+ `[persistence] symlink-escape on load: ${filePath} → ${canonical}, refusing`,
+ );
+ return;
}
const fileSize = statSync(canonical).size;
diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.ts
index fee623144..aef311ac0 100644
--- a/packages/server/src/server-factory.ts
+++ b/packages/server/src/server-factory.ts
@@ -110,6 +110,7 @@ import {
DerivedDocumentIndex,
type DerivedDocumentIndexBranchTransition,
} from './derived-document-index.ts';
+import { resolveDirectoryRoot } from './directory-root.ts';
import { applyDiskContentToDoc } from './disk-content-intake.ts';
import {
canonicalDocName,
@@ -513,6 +514,10 @@ export function createServer(options: ServerOptions): ServerInstance {
singleDocRelPath,
ephemeral = false,
} = options;
+ const canonicalContentDir = resolveDirectoryRoot(contentDir, {
+ root: 'content',
+ component: 'server-factory',
+ });
const declaredGitHubHosts = readDeclaredGitHubHosts(configHomedirOverride);
const resolveSyncCredentialConfig = createSyncCredentialConfigResolver({
projectDir,
@@ -1749,7 +1754,7 @@ export function createServer(options: ServerOptions): ServerInstance {
contentFilter,
getGlobalSkillRoots: () => managedArtifactSkillsRoots(persistence.managedArtifactCtx),
signalChannel,
- getLocalTargetInventory: () => localTargetInventoryFromWatcher(watcher, contentDir),
+ getLocalTargetInventory: () => localTargetInventoryFromWatcher(watcher, canonicalContentDir),
onRecoveredFileTarget: (relativePath, exists) => {
if (!watcher) return;
reconcileRecoveredFileTarget({
@@ -3965,7 +3970,7 @@ export function createServer(options: ServerOptions): ServerInstance {
const onRawBatch = (absPaths: readonly string[]): void => {
if (
!absPaths.some((p) =>
- HOST_SKILLS_EVENT_RE.test(relative(contentDir, p).split(sep).join('/')),
+ HOST_SKILLS_EVENT_RE.test(relative(canonicalContentDir, p).split(sep).join('/')),
)
) {
return;
@@ -4011,7 +4016,7 @@ export function createServer(options: ServerOptions): ServerInstance {
}, IN_PLACE_RESCAN_DEBOUNCE_MS);
};
watcher = await withSpan('ok.boot.seed-walk', undefined, async () =>
- startWatcher(contentDir, onDiskEvent, contentFilter, {
+ startWatcher(canonicalContentDir, onDiskEvent, contentFilter, {
onRawBatch,
onRecoveryComplete: () => derivedDocumentIndex.recordInventoryReconciled(),
}),
diff --git a/packages/server/tsconfig.test-helper-callers.json b/packages/server/tsconfig.test-helper-callers.json
index 348233549..5b96c4d91 100644
--- a/packages/server/tsconfig.test-helper-callers.json
+++ b/packages/server/tsconfig.test-helper-callers.json
@@ -8,6 +8,7 @@
"src/file-watcher-chokidar-readiness.test.ts",
"src/managed-artifact-watcher-readiness.test.ts",
"src/managed-artifact-watcher.test.ts",
+ "src/path-identity.test.ts",
"src/persistence-tripwire-block.test.ts",
"src/persistence-tripwire-paste.test.ts",
"src/polled-watcher-contract.test.ts",