@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/files/structured.js

@@ -0,0 +1,284 @@
+import { constants, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { base64, CHUNK_BYTES, identifier, integer, keys, string } from '../tools/validation.js';
+import { openMediaSource, pinned, resolveAbsolute } from './fence.js';
+import { configuredRoots, filesystemScope, inside, READ_ONLY } from './scope.js';
+import { MAX_UPLOAD_BYTES, TEMP_PREFIX, UPLOAD_TTL_MS, UploadStore } from './uploads.js';
+import { FileIndexCache } from './find/fileIndex.js';
+import { rankPaths } from './find/fuzzy.js';
+export const LIST_MAX_ENTRIES = 2000;
+export const LIST_MAX_VISITED = 10000;
+export const FIND_DEFAULT_LIMIT = 50;
+export const FIND_MAX_LIMIT = 200;
+/**
+ * The Files tab's file semantics (`files.*` tool requests): absolute paths in the `configured-roots` scope, or in the
+ * `read-only` scope when a request says `readOnly: true`. Errors are thrown with the messages callers see today
+ * (`tool_result.error`). Tools never compose a shell command.
+ */
+export class StructuredFiles {
+    scope;
+    uploads;
+    // Home and its ancestors walk instead of asking git: a dotfiles repository at `~` (often ignoring
+    // `*`) would answer for the whole home with just its tracked dotfiles.
+    indexes = new FileIndexCache(name => name.startsWith(TEMP_PREFIX), Date.now, scope => { const relative = path.relative(scope, this.home); return !relative.startsWith('..') && !path.isAbsolute(relative); });
+    home;
+    roots;
+    downloads;
+    constructor(scope, ttl, stateDir) {
+        this.scope = scope;
+        this.home = scope.home;
+        this.roots = [...scope.roots];
+        this.downloads = path.join(scope.home, 'Downloads');
+        this.uploads = new UploadStore(scope.roots, ttl, stateDir);
+    }
+    static async create(home, roots, ttl = UPLOAD_TTL_MS, stateDir, filesystem = false) {
+        const scope = filesystem ? await filesystemScope(home) : await configuredRoots(home, roots);
+        if (stateDir)
+            await UploadStore.prepareStateDir(stateDir);
+        const files = new StructuredFiles(scope, ttl, stateDir);
+        await files.uploads.recover((raw, missingLeaf, mutation) => files.resolve(raw, missingLeaf, mutation));
+        return files;
+    }
+    /** Uploads in flight. */
+    get activeUploads() { return this.uploads.size; }
+    scopeFor(readOnly) { return readOnly ? READ_ONLY : this.scope; }
+    /** Validates an absolute path in this instance's configured-roots scope (or the read-only scope). */
+    resolve(raw, missingLeaf = false, mutation = false, readOnly = false, followLeaf = true) {
+        return resolveAbsolute(this.scopeFor(readOnly), raw, missingLeaf, mutation, followLeaf);
+    }
+    /** The descriptor stays pinned after cwd is restored; media children inherit it, never re-open the path. */
+    openMediaSource(raw, readOnly = false) {
+        return openMediaSource(this.scopeFor(readOnly), raw);
+    }
+    async dispatch(method, p) {
+        if (p.readOnly !== undefined && typeof p.readOnly !== 'boolean')
+            throw new Error('Invalid readOnly');
+        if (p.readOnly !== undefined && !['files.list', 'files.find', 'files.read'].includes(method))
+            throw new Error('Read-only file access cannot modify files');
+        await this.expire();
+        if (method === 'files.find')
+            return this.find(p);
+        // Any write may add, move or remove a path a cached search list still holds. Invalidate before and again after
+        // the mutation: a search building its list concurrently (find takes no pin) then never caches a pre-mutation list.
+        if (!['files.list', 'files.read'].includes(method)) {
+            this.indexes.invalidate();
+            try {
+                return await this.locate(method, p);
+            }
+            finally {
+                this.indexes.invalidate();
+            }
+        }
+        return this.locate(method, p);
+    }
+    async locate(method, p) {
+        let parent;
+        if (method === 'files.upload.chunk' || method === 'files.upload.finish' || method === 'files.upload.cancel') {
+            const upload = this.uploads.get(identifier(p, 'uploadId'));
+            if (!upload && method === 'files.upload.cancel') {
+                keys(p, ['uploadId']);
+                return { ok: true };
+            }
+            if (!upload)
+                throw new Error('Upload not found or expired');
+            parent = path.dirname(upload.target);
+        }
+        else {
+            const target = await this.resolve(string(p, 'path', 4096, method === 'files.list' ? this.home : undefined), method === 'files.mkdir' || method === 'files.upload.begin', !['files.list', 'files.read'].includes(method), p.readOnly === true, !['files.rename', 'files.delete'].includes(method));
+            parent = method === 'files.list' ? target : path.dirname(target);
+        }
+        return pinned(parent, async (pin) => {
+            if (method.startsWith('files.upload.') && method !== 'files.upload.begin') {
+                // Re-read: the upload may have finished, been cancelled or expired while this call waited for the pin.
+                const upload = this.uploads.get(identifier(p, 'uploadId'));
+                if (!upload && method === 'files.upload.cancel') {
+                    keys(p, ['uploadId']);
+                    return { ok: true };
+                }
+                if (!upload)
+                    throw new Error('Upload not found or expired');
+                const stat = await fs.stat('.');
+                if (stat.dev !== upload.parent.dev || stat.ino !== upload.parent.ino) {
+                    if (method === 'files.upload.cancel') {
+                        await this.uploads.abandon(upload);
+                        return { ok: true };
+                    }
+                    throw new Error('Upload parent changed');
+                }
+            }
+            return this.perform(method, p, pin);
+        });
+    }
+    async perform(method, p, pin) {
+        switch (method) {
+            case 'files.list': {
+                keys(p, ['path', 'readOnly']);
+                const target = await this.resolve(string(p, 'path', 4096, this.home), false, false, p.readOnly === true);
+                const displayedPath = this.scope.kind === 'filesystem' ? string(p, 'path', 4096, this.home) : target;
+                const listing = await fs.opendir(pin.leaf(target));
+                const entries = [];
+                let visited = 0;
+                try {
+                    for await (const entry of listing) {
+                        if (++visited > LIST_MAX_VISITED || entries.length >= LIST_MAX_ENTRIES)
+                            throw new Error('Directory entry limit exceeded');
+                        if (entry.name.startsWith(TEMP_PREFIX) || entry.isSymbolicLink())
+                            continue;
+                        const entryPath = path.join(target, entry.name);
+                        let stat;
+                        try {
+                            await this.resolve(entryPath, false, false, p.readOnly === true);
+                            stat = await fs.lstat(pin.leaf(entryPath));
+                        }
+                        catch {
+                            continue;
+                        }
+                        if (!stat.isFile() && !stat.isDirectory())
+                            continue;
+                        entries.push({ name: entry.name, path: path.join(displayedPath, entry.name), directory: stat.isDirectory(), size: stat.size, modifiedAt: stat.mtimeMs, createdAt: stat.birthtimeMs > 0 ? stat.birthtimeMs : stat.ctimeMs > 0 ? stat.ctimeMs : stat.mtimeMs,
+                            ...(this.scope.kind === 'filesystem' ? { writable: await fs.access(entryPath, constants.W_OK).then(() => true, () => false) } : {}) });
+                    }
+                }
+                finally {
+                    await listing.close().catch(() => { });
+                }
+                entries.sort((a, b) => Number(b.directory) - Number(a.directory) || String(a.name).localeCompare(String(b.name)));
+                const parent = path.dirname(displayedPath);
+                return { path: displayedPath, parent: p.readOnly === true || this.scope.kind === 'filesystem' ? (parent === displayedPath ? null : parent) : this.roots.includes(target) || !this.roots.some(root => inside(parent, root)) ? null : parent, entries, roots: this.roots };
+            }
+            case 'files.read': {
+                keys(p, ['path', 'offset', 'length', 'readOnly']);
+                const offset = integer(p, 'offset', 0, Number.MAX_SAFE_INTEGER, 0);
+                const length = integer(p, 'length', 1, CHUNK_BYTES, CHUNK_BYTES);
+                const target = await this.resolve(string(p, 'path'), false, false, p.readOnly === true);
+                const handle = await pin.regularHandle(target);
+                try {
+                    const stat = await handle.stat();
+                    const buffer = Buffer.alloc(length);
+                    const { bytesRead } = await handle.read(buffer, 0, length, offset);
+                    return { data: buffer.subarray(0, bytesRead).toString('base64'), size: stat.size, eof: offset + bytesRead >= stat.size, name: path.basename(target),
+                        ...(this.scope.kind === 'filesystem' ? { writable: await fs.access(pin.leaf(target), constants.W_OK).then(() => true, () => false) } : {}) };
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+            case 'files.mkdir': {
+                keys(p, ['path']);
+                const target = await this.resolve(string(p, 'path'), true, true);
+                await fs.mkdir(pin.leaf(target));
+                return { ok: true };
+            }
+            case 'files.rename': {
+                keys(p, ['path', 'name']);
+                const target = await this.resolve(string(p, 'path'), false, true, false, false);
+                const name = string(p, 'name', 255);
+                if (name === '.' || name === '..' || /[/\\]/.test(name) || name.startsWith(TEMP_PREFIX))
+                    throw new Error('Invalid new name');
+                const destination = await this.resolve(path.join(path.dirname(target), name), true, true);
+                // Node rename() overwrites files. Hard-link commits are exclusive for files; for directories,
+                // reserve the destination with mkdir and replace only that empty reservation atomically.
+                const stat = await fs.lstat(pin.leaf(target));
+                if (stat.isFile()) {
+                    await fs.link(pin.leaf(target), pin.leaf(destination));
+                    await fs.unlink(pin.leaf(target));
+                }
+                else if (stat.isDirectory()) {
+                    await fs.mkdir(pin.leaf(destination), { mode: stat.mode });
+                    try {
+                        await fs.rename(pin.leaf(target), pin.leaf(destination));
+                    }
+                    catch (error) {
+                        await fs.rmdir(pin.leaf(destination)).catch(() => { });
+                        throw error;
+                    }
+                }
+                else
+                    throw new Error('Not a regular file or directory');
+                return { ok: true };
+            }
+            case 'files.delete': {
+                keys(p, ['path']);
+                const target = await this.resolve(string(p, 'path'), false, true, false, false);
+                const stat = await fs.lstat(pin.leaf(target));
+                if (stat.isDirectory())
+                    await fs.rmdir(pin.leaf(target));
+                else if (stat.isFile())
+                    await fs.unlink(pin.leaf(target));
+                else
+                    throw new Error('Not a regular file or directory');
+                return { ok: true };
+            }
+            case 'files.upload.begin': {
+                keys(p, ['path', 'size', 'overwrite']);
+                const size = integer(p, 'size', 0, MAX_UPLOAD_BYTES);
+                if (p.overwrite !== undefined && typeof p.overwrite !== 'boolean')
+                    throw new Error('Invalid overwrite');
+                return this.uploads.begin(pin, () => this.resolve(string(p, 'path'), true, true), size, p.overwrite === true, this.scope.kind === 'filesystem', string(p, 'path'));
+            }
+            case 'files.upload.chunk': {
+                keys(p, ['uploadId', 'offset', 'data']);
+                const upload = this.uploads.use(identifier(p, 'uploadId'));
+                const offset = integer(p, 'offset', 0, MAX_UPLOAD_BYTES);
+                const bytes = base64(p.data);
+                return this.uploads.chunk(upload, offset, bytes);
+            }
+            case 'files.upload.finish': {
+                keys(p, ['uploadId']);
+                const upload = this.uploads.use(identifier(p, 'uploadId'));
+                return this.uploads.finish(pin, upload, (raw, missingLeaf, mutation) => this.resolve(raw, missingLeaf, mutation));
+            }
+            case 'files.upload.cancel': {
+                keys(p, ['uploadId']);
+                return this.uploads.cancel(identifier(p, 'uploadId'));
+            }
+            default: throw new Error('Unsupported file tool');
+        }
+    }
+    /**
+     * Fuzzy file-name search below one directory (`path`, default home). Ranking runs over the cached
+     * relative-path list; only the best candidates are re-validated against the same root/symlink fence
+     * as `files.list` before they are returned, so a path git still remembers but the disk lost, or one
+     * that became a symbolic link, never reaches the client. Uses no cwd: absolute paths throughout, so it
+     * never enters (or waits for) a `pinned()` section.
+     */
+    async find(p) {
+        keys(p, ['path', 'query', 'limit', 'readOnly']);
+        const readOnly = p.readOnly === true;
+        const query = string(p, 'query', 256).trim();
+        if (!query)
+            throw new Error('Invalid query');
+        const limit = integer(p, 'limit', 1, FIND_MAX_LIMIT, FIND_DEFAULT_LIMIT);
+        const scope = await this.resolve(string(p, 'path', 4096, this.home), false, false, readOnly);
+        const displayedScope = this.scope.kind === 'filesystem' ? string(p, 'path', 4096, this.home) : scope;
+        if (!(await fs.stat(scope)).isDirectory())
+            throw new Error('Search scope is not a directory');
+        const index = await this.indexes.get(scope);
+        const ranked = rankPaths(index.paths, query);
+        const entries = [];
+        let checked = 0;
+        // Bounded: a stale list full of vanished paths must not turn one search into a disk scan.
+        for (const hit of ranked.slice(0, limit * 4)) {
+            if (entries.length >= limit)
+                break;
+            checked++;
+            const relative = index.paths[hit.index];
+            const target = path.join(scope, relative);
+            let stat;
+            try {
+                await this.resolve(target, false, false, readOnly);
+                stat = await fs.lstat(target);
+            }
+            catch {
+                continue;
+            }
+            if (!stat.isFile() && !stat.isDirectory())
+                continue;
+            entries.push({ name: path.basename(relative), path: path.join(displayedScope, relative), directory: stat.isDirectory(), match: relative, positions: hit.positions });
+        }
+        // Candidates the fence dropped are not matches; the unchecked tail is counted as is.
+        return { path: displayedScope, entries, total: entries.length + ranked.length - checked, truncated: index.truncated, source: index.source };
+    }
+    async expire() { await this.uploads.expire(); }
+    async dispose() { await this.uploads.dispose(); }
+}

package/dist/workstation/files/text.js

@@ -0,0 +1,356 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { link, lstat, mkdir, open, readdir, rename, stat, unlink } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { canonicalRoot, FileError, pinned, resolvePinnedDir, resolvePinnedDirCreate, resolvePinnedLeaf, resolveRelativeDir, resolveRelativeDirCreate, resolveRelativeFile, throwIfAborted, toFileError, withinRoot, } from './fence.js';
+import { assertScopeAllows } from './scope.js';
+/** Text file semantics of the platform agent tools (`file_*_request`): request-root scope only. */
+export const MAX_READ_BYTES = 8 * 1024 * 1024;
+export const MAX_PAGE_BYTES = 256 * 1024;
+export const MAX_WRITE_BYTES = 1024 * 1024;
+// Transport-free engines (formerly fileOps.ts). Untrusted requests must go through the scope entry points at the
+// bottom of this file (or the legacy fork-per-request worker), which pin the parent directory before invoking these
+// with a pinned leaf resolver; pathname-only resolution here is retained for unit tests and trusted callers, not as a
+// security boundary against rename races.
+const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
+async function snapshotFile(file, signal) {
+    let handle;
+    try {
+        handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        const before = await handle.stat({ bigint: true });
+        if (!before.isFile())
+            throw new FileError('not_regular_file', 'Target is not a regular file');
+        if (before.size > BigInt(MAX_READ_BYTES))
+            throw new FileError('too_large', 'File exceeds 8 MiB');
+        const parts = [];
+        let total = 0;
+        while (true) {
+            throwIfAborted(signal);
+            const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, MAX_READ_BYTES + 1 - total));
+            const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
+            if (!bytesRead)
+                break;
+            total += bytesRead;
+            if (total > MAX_READ_BYTES)
+                throw new FileError('too_large', 'File exceeds 8 MiB');
+            parts.push(chunk.subarray(0, bytesRead));
+        }
+        const after = await handle.stat({ bigint: true });
+        if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeNs !== after.mtimeNs || before.ctimeNs !== after.ctimeNs || BigInt(total) !== after.size) {
+            throw new FileError('conflict', 'File changed during read');
+        }
+        return Buffer.concat(parts, total);
+    }
+    catch (error) {
+        throw toFileError(error);
+    }
+    finally {
+        await handle?.close();
+    }
+}
+export async function readTextFile(request, signal, resolvePath = resolveRelativeFile) {
+    if (!Number.isSafeInteger(request.startLine) || request.startLine < 1 || !Number.isSafeInteger(request.maxLines) || request.maxLines < 1 || request.maxLines > 2000) {
+        throw new FileError('invalid_argument', 'Invalid line range');
+    }
+    const file = await resolvePath(request.root, request.path, false);
+    let bytes;
+    try {
+        bytes = await snapshotFile(file, signal);
+    }
+    catch (error) {
+        if (!(error instanceof FileError) || error.code !== 'conflict')
+            throw error;
+        bytes = await snapshotFile(file, signal);
+    }
+    let source;
+    try {
+        source = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        throw new FileError('invalid_encoding', 'File is not valid UTF-8');
+    }
+    const lines = [];
+    for (let begin = 0; begin < source.length;) {
+        const newline = source.indexOf('\n', begin);
+        const end = newline < 0 ? source.length : newline + 1;
+        lines.push(source.slice(begin, end));
+        begin = end;
+    }
+    const first = request.startLine - 1;
+    let content = '';
+    let selected = 0;
+    let pageBytes = 0;
+    for (let index = first; index < lines.length && selected < request.maxLines; index++) {
+        const lineBytes = Buffer.byteLength(lines[index], 'utf8');
+        if (lineBytes > MAX_PAGE_BYTES)
+            throw new FileError('line_too_long', 'A line exceeds 256 KiB');
+        if (pageBytes + lineBytes > MAX_PAGE_BYTES)
+            break;
+        content += lines[index];
+        pageBytes += lineBytes;
+        selected++;
+    }
+    const next = first + selected < lines.length ? request.startLine + selected : undefined;
+    return {
+        path: request.path, content, startLine: request.startLine,
+        endLine: selected ? request.startLine + selected - 1 : 0,
+        ...(next !== undefined ? { nextLine: next } : {}), truncated: next !== undefined,
+        sizeBytes: bytes.length, sha256: hash(bytes),
+    };
+}
+const writeLocks = new Map();
+async function serialWrite(target, action) {
+    const previous = writeLocks.get(target) ?? Promise.resolve();
+    let release;
+    const gate = new Promise(resolve => { release = resolve; });
+    const queued = previous.then(() => gate);
+    writeLocks.set(target, queued);
+    await previous;
+    try {
+        return await action();
+    }
+    finally {
+        release();
+        if (writeLocks.get(target) === queued)
+            writeLocks.delete(target);
+    }
+}
+function validUnicode(content) {
+    for (let index = 0; index < content.length; index++) {
+        const code = content.charCodeAt(index);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = content.charCodeAt(++index);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                return false;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff)
+            return false;
+    }
+    return true;
+}
+export async function writeTextFile(request, signal, resolvePath = resolveRelativeFile) {
+    if (request.content.includes('\0') || !validUnicode(request.content)) {
+        throw new FileError('invalid_encoding', 'Content must be valid UTF-8 text without NUL');
+    }
+    const bytes = Buffer.from(request.content, 'utf8');
+    if (bytes.length > MAX_WRITE_BYTES)
+        throw new FileError('too_large', 'Content exceeds 1 MiB');
+    if (request.mode !== 'create' && request.mode !== 'replace')
+        throw new FileError('invalid_argument', 'Invalid write mode');
+    if (request.mode === 'create' ? request.expectedSha256 !== undefined : !/^[0-9a-f]{64}$/.test(request.expectedSha256 ?? '')) {
+        throw new FileError('invalid_argument', 'create forbids expected_sha256; replace requires lowercase SHA-256');
+    }
+    throwIfAborted(signal);
+    const file = await resolvePath(request.root, request.path, request.mode === 'create');
+    return serialWrite(file, async () => {
+        throwIfAborted(signal);
+        await resolvePath(request.root, request.path, request.mode === 'create');
+        let mode = 0o666;
+        if (request.mode === 'replace') {
+            const current = await snapshotFile(file, signal);
+            if (hash(current) !== request.expectedSha256)
+                throw new FileError('conflict', 'File changed since it was read');
+            try {
+                mode = (await stat(file)).mode & 0o777;
+            }
+            catch (error) {
+                throw toFileError(error);
+            }
+        }
+        const parent = dirname(file);
+        const temporary = join(parent, `.${basename(file)}.axom-${randomUUID()}.tmp`);
+        let handle;
+        try {
+            handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), mode);
+            if (request.mode === 'replace' && process.platform !== 'win32')
+                await handle.chmod(mode);
+            await handle.writeFile(bytes);
+            await handle.sync();
+            await handle.close();
+            handle = undefined;
+            throwIfAborted(signal);
+            await resolvePath(request.root, request.path, request.mode === 'create');
+            if (request.mode === 'create')
+                await link(temporary, file);
+            else
+                await rename(temporary, file);
+            return { path: request.path, sizeBytes: bytes.length, sha256: hash(bytes), created: request.mode === 'create' };
+        }
+        catch (error) {
+            throw toFileError(error);
+        }
+        finally {
+            await handle?.close();
+            await unlink(temporary).catch(error => { if (error.code !== 'ENOENT')
+                throw toFileError(error); });
+        }
+    });
+}
+export async function listTextDir(request, signal, resolvePath = resolveRelativeDir) {
+    if (!Number.isSafeInteger(request.maxEntries) || request.maxEntries < 1 || request.maxEntries > 2000) {
+        throw new FileError('invalid_argument', 'Invalid entry range');
+    }
+    throwIfAborted(signal);
+    const dir = await resolvePath(request.root, request.path);
+    throwIfAborted(signal);
+    const dirents = (await readdir(dir, { withFileTypes: true }))
+        .sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+    const entries = [];
+    let truncated = false;
+    for (const dirent of dirents) {
+        if (request.startAfter !== undefined && !(dirent.name > request.startAfter))
+            continue;
+        if (entries.length >= request.maxEntries) {
+            truncated = true;
+            break;
+        }
+        let kind;
+        if (dirent.isFile())
+            kind = 'file';
+        else if (dirent.isDirectory())
+            kind = 'directory';
+        else if (dirent.isSymbolicLink())
+            kind = 'symlink';
+        else {
+            // Filesystems that report DT_UNKNOWN leave the kind to a fresh lstat.
+            try {
+                const entry = await lstat(join(dir, dirent.name));
+                kind = entry.isFile() ? 'file' : entry.isDirectory() ? 'directory' : entry.isSymbolicLink() ? 'symlink' : 'other';
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw toFileError(error);
+                continue;
+            }
+        }
+        const entry = { name: dirent.name, kind };
+        if (kind === 'file') {
+            try {
+                entry.sizeBytes = (await lstat(join(dir, dirent.name))).size;
+            }
+            catch (error) {
+                // A file that vanished between readdir and lstat simply drops out of the snapshot.
+                if (error.code !== 'ENOENT')
+                    throw toFileError(error);
+                continue;
+            }
+        }
+        entries.push(entry);
+    }
+    const nextAfter = truncated ? entries[entries.length - 1]?.name : undefined;
+    return { path: request.path, entries, truncated, ...(nextAfter !== undefined ? { nextAfter } : {}) };
+}
+export async function createTextDir(request, signal, resolvePlan = resolveRelativeDirCreate) {
+    throwIfAborted(signal);
+    const plan = await resolvePlan(request.root, request.path, request.parents);
+    if (plan.missing.length === 0) {
+        if (!request.parents)
+            throw new FileError('conflict', 'Target already exists');
+        return { path: request.path, created: false };
+    }
+    if (!request.parents && plan.missing.length > 1) {
+        throw new FileError('not_found', 'Parent directory not found');
+    }
+    let cursor = plan.anchor;
+    let created = false;
+    for (const component of plan.missing) {
+        throwIfAborted(signal);
+        const target = join(cursor, component);
+        try {
+            await mkdir(target);
+            created = true;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw toFileError(error);
+            if (!request.parents)
+                throw new FileError('conflict', 'Target already exists');
+        }
+        // A component we just made (or found racing us) must be a real directory, never a symlink stand-in.
+        const entry = await lstat(target).catch(error => { throw toFileError(error); });
+        if (entry.isSymbolicLink() || !entry.isDirectory())
+            throw new FileError('conflict', 'Path is not a directory');
+        cursor = target;
+    }
+    return { path: request.path, created };
+}
+const targetLocks = new Map();
+async function serialTarget(target, action) {
+    const previous = targetLocks.get(target) ?? Promise.resolve();
+    let release;
+    const gate = new Promise(resolve => { release = resolve; });
+    const queued = previous.then(() => gate);
+    targetLocks.set(target, queued);
+    await previous;
+    try {
+        return await action();
+    }
+    finally {
+        release();
+        if (targetLocks.get(target) === queued)
+            targetLocks.delete(target);
+    }
+}
+// The worker client checked for cancellation after pathname validation, when it was about to start the operation.
+async function throwIfAbortedThen(signal, run) {
+    throwIfAborted(signal);
+    return run();
+}
+function requireRequestRoot(scope, operation) {
+    if (scope?.kind !== 'request-root')
+        throw new FileError('invalid_argument', 'Text file operations require a request root');
+    assertScopeAllows(scope, operation);
+}
+/**
+ * Runs `run` with the cwd pinned to `anchor`, which must still be inside the canonical root after chdir. Cancellation
+ * keeps the file worker's contract: a request cancelled once it is under way reports `outcome_unknown` for mutations
+ * and `workstation_offline` for reads.
+ */
+async function anchored(operation, root, anchor, signal, hooks, run) {
+    try {
+        await hooks?.afterValidation?.();
+        return await pinned(anchor, async () => {
+            await hooks?.afterPinned?.();
+            throwIfAborted(signal);
+            return run();
+        }, { verify: withinRoot(root), signal });
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw new FileError(operation === 'write' || operation === 'mkdir' ? 'outcome_unknown' : 'workstation_offline', 'File operation was cancelled');
+        throw toFileError(error);
+    }
+}
+export async function readText(scope, request, signal, hooks) {
+    requireRequestRoot(scope, 'read');
+    const root = await canonicalRoot(scope.root);
+    const target = await resolveRelativeFile(root, request.path, false);
+    throwIfAborted(signal);
+    // As the file worker did, the result names the leaf it read.
+    return anchored('read', root, dirname(target), signal, hooks, () => readTextFile({ ...request, root: '.', path: basename(target) }, signal, resolvePinnedLeaf));
+}
+export async function writeText(scope, request, signal, hooks) {
+    requireRequestRoot(scope, 'write');
+    const root = await canonicalRoot(scope.root);
+    const target = await resolveRelativeFile(root, request.path, request.mode === 'create');
+    return serialTarget(target, () => throwIfAbortedThen(signal, () => anchored('write', root, dirname(target), signal, hooks, () => writeTextFile({ ...request, root: '.', path: basename(target) }, signal, resolvePinnedLeaf))));
+}
+export async function listDir(scope, request, signal, hooks) {
+    requireRequestRoot(scope, 'list');
+    const root = await canonicalRoot(scope.root);
+    const target = await resolveRelativeDir(root, request.path);
+    throwIfAborted(signal);
+    // Listing the root pins the root itself; '' is the zero-component leaf.
+    const anchor = target === root ? root : dirname(target);
+    const leaf = target === root ? '' : basename(target);
+    const data = await anchored('list', root, anchor, signal, hooks, () => listTextDir({ ...request, root: '.', path: leaf }, signal, resolvePinnedDir));
+    return { ...data, path: request.path };
+}
+export async function makeDir(scope, request, signal, hooks) {
+    requireRequestRoot(scope, 'mkdir');
+    const root = await canonicalRoot(scope.root);
+    const plan = await resolveRelativeDirCreate(root, request.path, request.parents);
+    throwIfAborted(signal);
+    const data = await anchored('mkdir', root, plan.anchor, signal, hooks, () => createTextDir({ ...request, root: '.', path: plan.missing.join('/') }, signal, resolvePinnedDirCreate));
+    return { ...data, path: request.path };
+}