@platless/axom-cli 0.1.0 → 0.3.13

package/dist/workstation/fileOps.js

@@ -0,0 +1,277 @@
+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 { ComputerFileError, computerFileError, resolveComputerDirCreatePath, resolveComputerDirPath, resolveComputerFilePath } from './filePaths.js';
+export const MAX_READ_BYTES = 8 * 1024 * 1024;
+export const MAX_PAGE_BYTES = 256 * 1024;
+export const MAX_WRITE_BYTES = 1024 * 1024;
+// Transport-free primitives. Untrusted channel requests must use fileWorkerClient, which pins the
+// parent directory before invoking these with resolvePinnedLeafPath; 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');
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw new ComputerFileError('workstation_offline', 'File operation was cancelled');
+}
+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 ComputerFileError('not_regular_file', 'Target is not a regular file');
+        if (before.size > BigInt(MAX_READ_BYTES))
+            throw new ComputerFileError('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 ComputerFileError('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 ComputerFileError('conflict', 'File changed during read');
+        }
+        return Buffer.concat(parts, total);
+    }
+    catch (error) {
+        throw computerFileError(error);
+    }
+    finally {
+        await handle?.close();
+    }
+}
+export async function readComputerFile(request, signal, resolvePath = resolveComputerFilePath) {
+    if (!Number.isSafeInteger(request.startLine) || request.startLine < 1 || !Number.isSafeInteger(request.maxLines) || request.maxLines < 1 || request.maxLines > 2000) {
+        throw new ComputerFileError('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 ComputerFileError) || 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 ComputerFileError('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 ComputerFileError('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 writeComputerFile(request, signal, resolvePath = resolveComputerFilePath) {
+    if (request.content.includes('\0') || !validUnicode(request.content)) {
+        throw new ComputerFileError('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 ComputerFileError('too_large', 'Content exceeds 1 MiB');
+    if (request.mode !== 'create' && request.mode !== 'replace')
+        throw new ComputerFileError('invalid_argument', 'Invalid write mode');
+    if (request.mode === 'create' ? request.expectedSha256 !== undefined : !/^[0-9a-f]{64}$/.test(request.expectedSha256 ?? '')) {
+        throw new ComputerFileError('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 ComputerFileError('conflict', 'File changed since it was read');
+            try {
+                mode = (await stat(file)).mode & 0o777;
+            }
+            catch (error) {
+                throw computerFileError(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 computerFileError(error);
+        }
+        finally {
+            await handle?.close();
+            await unlink(temporary).catch(error => { if (error.code !== 'ENOENT')
+                throw computerFileError(error); });
+        }
+    });
+}
+export async function listComputerDir(request, signal, resolvePath = resolveComputerDirPath) {
+    if (!Number.isSafeInteger(request.maxEntries) || request.maxEntries < 1 || request.maxEntries > 2000) {
+        throw new ComputerFileError('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 computerFileError(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 computerFileError(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 createComputerDir(request, signal, resolvePlan = resolveComputerDirCreatePath) {
+    throwIfAborted(signal);
+    const plan = await resolvePlan(request.root, request.path, request.parents);
+    if (plan.missing.length === 0) {
+        if (!request.parents)
+            throw new ComputerFileError('conflict', 'Target already exists');
+        return { path: request.path, created: false };
+    }
+    if (!request.parents && plan.missing.length > 1) {
+        throw new ComputerFileError('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 computerFileError(error);
+            if (!request.parents)
+                throw new ComputerFileError('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 computerFileError(error); });
+        if (entry.isSymbolicLink() || !entry.isDirectory())
+            throw new ComputerFileError('conflict', 'Path is not a directory');
+        cursor = target;
+    }
+    return { path: request.path, created };
+}

package/dist/workstation/filePaths.js

@@ -0,0 +1,174 @@
+import { lstat, realpath } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+export class ComputerFileError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ComputerFileError';
+    }
+}
+export function computerFileError(error) {
+    if (error instanceof ComputerFileError)
+        return error;
+    const code = error?.code;
+    if (code === 'ENOENT')
+        return new ComputerFileError('not_found', 'File or parent directory not found');
+    if (code === 'EACCES' || code === 'EPERM')
+        return new ComputerFileError('permission_denied', 'File access denied');
+    if (code === 'EEXIST')
+        return new ComputerFileError('conflict', 'Target already exists');
+    if (code === 'ELOOP')
+        return new ComputerFileError('invalid_path', 'Symbolic links are not allowed');
+    return new ComputerFileError('io_error', 'File operation failed');
+}
+/** Validate portable slash components before touching the filesystem. */
+export function validateComputerFilePath(path) {
+    if (!path || path.includes('\\') || path.includes(':') || path.includes('\0') || isAbsolute(path)) {
+        throw new ComputerFileError('invalid_path', 'Path must be relative to the selected workspace');
+    }
+    const components = path.split('/');
+    if (components.some(component => !component || component === '.' || component === '..')) {
+        throw new ComputerFileError('invalid_path', 'Path contains an unsafe component');
+    }
+    return components;
+}
+/** The configured root may itself be a symlink; none of its descendants may be. */
+export async function resolveComputerFilePath(root, path, allowMissingLeaf) {
+    const components = validateComputerFilePath(path);
+    let cursor;
+    try {
+        cursor = await realpath(root);
+    }
+    catch (error) {
+        throw computerFileError(error);
+    }
+    for (let index = 0; index < components.length; index++) {
+        cursor = join(cursor, components[index]);
+        let stat;
+        try {
+            stat = await lstat(cursor);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT' && allowMissingLeaf && index === components.length - 1)
+                return cursor;
+            throw computerFileError(error);
+        }
+        if (stat.isSymbolicLink())
+            throw new ComputerFileError('invalid_path', 'Symbolic links are not allowed');
+        if (index === components.length - 1) {
+            if (!stat.isFile())
+                throw new ComputerFileError('not_regular_file', 'Target is not a regular file');
+        }
+        else if (!stat.isDirectory()) {
+            throw new ComputerFileError('not_regular_file', 'Parent is not a directory');
+        }
+    }
+    return cursor;
+}
+/** Resolve only a leaf relative to an already pinned process cwd; never turn it back into an absolute pathname. */
+export async function resolvePinnedLeafPath(_root, path, allowMissingLeaf) {
+    const components = validateComputerFilePath(path);
+    if (components.length !== 1)
+        throw new ComputerFileError('invalid_path', 'Pinned file operation requires one path component');
+    try {
+        const entry = await lstat(path);
+        if (entry.isSymbolicLink())
+            throw new ComputerFileError('invalid_path', 'Symbolic links are not allowed');
+        if (!entry.isFile())
+            throw new ComputerFileError('not_regular_file', 'Target is not a regular file');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT' || !allowMissingLeaf)
+            throw computerFileError(error);
+    }
+    return path;
+}
+/** Every component of a directory listing target must exist, be a directory, and not be a symlink; '' is the root. */
+export async function resolveComputerDirPath(root, path) {
+    const components = path === '' ? [] : validateComputerFilePath(path);
+    let cursor;
+    try {
+        cursor = await realpath(root);
+    }
+    catch (error) {
+        throw computerFileError(error);
+    }
+    for (const component of components) {
+        cursor = join(cursor, component);
+        let entry;
+        try {
+            entry = await lstat(cursor);
+        }
+        catch (error) {
+            throw computerFileError(error);
+        }
+        if (entry.isSymbolicLink())
+            throw new ComputerFileError('invalid_path', 'Symbolic links are not allowed');
+        if (!entry.isDirectory())
+            throw new ComputerFileError('not_regular_file', 'Target is not a directory');
+    }
+    return cursor;
+}
+/** Pinned variant for the file worker: '' lists the pinned cwd itself, otherwise exactly one component. */
+export async function resolvePinnedDirPath(_root, path) {
+    const components = path === '' ? [] : validateComputerFilePath(path);
+    if (components.length > 1)
+        throw new ComputerFileError('invalid_path', 'Pinned directory operation requires at most one path component');
+    const target = path === '' ? '.' : join('.', path);
+    let entry;
+    try {
+        entry = await lstat(target);
+    }
+    catch (error) {
+        throw computerFileError(error);
+    }
+    if (entry.isSymbolicLink())
+        throw new ComputerFileError('invalid_path', 'Symbolic links are not allowed');
+    if (!entry.isDirectory())
+        throw new ComputerFileError('not_regular_file', 'Target is not a directory');
+    return target;
+}
+/**
+ * Locate the deepest existing ancestor for a directory creation. Without parents the anchor must be the
+ * target's own parent (only the leaf may be missing); with parents any prefix may be missing. Existing
+ * components must be directories and never symlinks; an existing leaf counts as "already created".
+ */
+export async function resolveComputerDirCreatePath(root, path, parents) {
+    const components = validateComputerFilePath(path);
+    let cursor;
+    try {
+        cursor = await realpath(root);
+    }
+    catch (error) {
+        throw computerFileError(error);
+    }
+    let anchorIndex = 0;
+    for (; anchorIndex < components.length; anchorIndex++) {
+        const candidate = join(cursor, components[anchorIndex]);
+        let entry;
+        try {
+            entry = await lstat(candidate);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw computerFileError(error);
+            break;
+        }
+        if (entry.isSymbolicLink())
+            throw new ComputerFileError('invalid_path', 'Symbolic links are not allowed');
+        if (!entry.isDirectory())
+            throw new ComputerFileError('not_found', 'Path is not a directory');
+        cursor = candidate;
+    }
+    const missing = components.slice(anchorIndex);
+    if (!parents && missing.length > 1) {
+        throw new ComputerFileError('not_found', 'Parent directory not found');
+    }
+    return { anchor: cursor, missing };
+}
+/** Pinned variant for the file worker: create the missing components below the pinned cwd, one leaf at a time. */
+export async function resolvePinnedDirCreatePath(_root, path, _parents) {
+    const components = path === '' ? [] : validateComputerFilePath(path);
+    return { anchor: '.', missing: components };
+}

package/dist/workstation/fileWorker.js

@@ -0,0 +1,81 @@
+import { realpath } from 'node:fs/promises';
+import { isAbsolute, relative, sep } from 'node:path';
+import { computerFileError, ComputerFileError, resolvePinnedDirCreatePath, resolvePinnedDirPath, resolvePinnedLeafPath, } from './filePaths.js';
+import { createComputerDir, listComputerDir, readComputerFile, writeComputerFile, } from './fileOps.js';
+const controller = new AbortController();
+let started = false;
+let pending;
+/**
+ * This worker is a separate process so its cwd is a kernel-pinned directory reference, not a
+ * pathname re-resolved after validation. A swapped ancestor symlink may affect process launch,
+ * but the post-launch realpath check then rejects it before touching the leaf. Directory
+ * operations accept at most one pinned component: multi-component `parents` creation walks
+ * one leaf at a time from the pinned anchor instead of re-resolving full pathnames.
+ */
+process.on('message', (message) => {
+    if (message.kind === 'cancel') {
+        controller.abort();
+        if (pending) {
+            pending = undefined;
+            process.disconnect();
+        }
+        return;
+    }
+    if (message.kind === 'continue') {
+        const work = pending;
+        if (!work)
+            return;
+        pending = undefined;
+        void (async () => {
+            try {
+                if (work.kind === 'read') {
+                    const request = { ...work.request, root: '.' };
+                    const data = await readComputerFile(request, controller.signal, resolvePinnedLeafPath);
+                    process.send?.({ ok: true, data }, () => process.disconnect());
+                }
+                else if (work.kind === 'write') {
+                    const request = { ...work.request, root: '.' };
+                    const data = await writeComputerFile(request, controller.signal, resolvePinnedLeafPath);
+                    process.send?.({ ok: true, data }, () => process.disconnect());
+                }
+                else if (work.kind === 'ls') {
+                    const request = { ...work.request, root: '.' };
+                    const data = await listComputerDir(request, controller.signal, resolvePinnedDirPath);
+                    process.send?.({ ok: true, data }, () => process.disconnect());
+                }
+                else {
+                    const request = { ...work.request, root: '.' };
+                    const data = await createComputerDir(request, controller.signal, resolvePinnedDirCreatePath);
+                    process.send?.({ ok: true, data }, () => process.disconnect());
+                }
+            }
+            catch (error) {
+                const mapped = computerFileError(error);
+                process.send?.({ ok: false, error: { code: mapped.code, message: mapped.message } }, () => process.disconnect());
+            }
+        })();
+        return;
+    }
+    if (started)
+        return;
+    started = true;
+    void (async () => {
+        try {
+            const parent = await realpath('.');
+            const rel = relative(message.root, parent);
+            if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+                throw new ComputerFileError('invalid_path', 'File parent escaped the configured workspace');
+            }
+            if (controller.signal.aborted) {
+                process.disconnect();
+                return;
+            }
+            pending = message;
+            process.send?.({ kind: 'ready' });
+        }
+        catch (error) {
+            const mapped = computerFileError(error);
+            process.send?.({ ok: false, error: { code: mapped.code, message: mapped.message } }, () => process.disconnect());
+        }
+    })();
+});

package/dist/workstation/fileWorkerClient.js

@@ -0,0 +1,121 @@
+import { fork } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { realpath } from 'node:fs/promises';
+import { basename, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ComputerFileError, computerFileError, resolveComputerDirCreatePath, resolveComputerDirPath, resolveComputerFilePath } from './filePaths.js';
+const workerUrl = existsSync(new URL('./fileWorker.js', import.meta.url))
+    ? new URL('./fileWorker.js', import.meta.url)
+    : new URL('../../dist/workstation/fileWorker.js', import.meta.url);
+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);
+    }
+}
+async function execute(kind, request, anchor, leaf, signal, hooks) {
+    if (signal?.aborted)
+        throw new ComputerFileError('workstation_offline', 'File operation was cancelled');
+    const root = await realpath(request.root).catch(error => { throw computerFileError(error); });
+    await hooks?.afterValidation?.();
+    return new Promise((resolve, reject) => {
+        const child = fork(fileURLToPath(workerUrl), [], {
+            cwd: anchor, stdio: ['ignore', 'ignore', 'ignore', 'ipc'], execArgv: [],
+        });
+        let settled = false;
+        let killTimer;
+        const finish = (error, data) => {
+            if (settled)
+                return;
+            settled = true;
+            signal?.removeEventListener('abort', abort);
+            if (error)
+                reject(error);
+            else
+                resolve(data);
+        };
+        const abort = () => {
+            if (settled)
+                return;
+            child.send({ kind: 'cancel' }, () => { });
+            killTimer = setTimeout(() => child.kill(), 2_000);
+            killTimer.unref();
+            finish(new ComputerFileError(kind === 'write' || kind === 'mkdir' ? 'outcome_unknown' : 'workstation_offline', 'File operation was cancelled'));
+        };
+        child.on('message', (message) => {
+            if (typeof message !== 'object' || message === null)
+                return;
+            const reply = message;
+            if (reply.kind === 'ready') {
+                void (async () => {
+                    try {
+                        await hooks?.afterWorkerReady?.();
+                        if (!settled)
+                            child.send({ kind: 'continue' }, error => { if (error)
+                                finish(computerFileError(error)); });
+                    }
+                    catch (error) {
+                        child.kill();
+                        finish(computerFileError(error));
+                    }
+                })();
+                return;
+            }
+            if (reply.ok === true)
+                finish(undefined, reply.data);
+            else if (reply.ok === false && reply.error)
+                finish(new ComputerFileError(reply.error.code, reply.error.message));
+        });
+        child.once('error', error => finish(computerFileError(error)));
+        child.once('exit', () => {
+            if (killTimer)
+                clearTimeout(killTimer);
+            finish(new ComputerFileError(kind === 'write' || kind === 'mkdir' ? 'outcome_unknown' : 'workstation_offline', 'File worker exited without a result'));
+        });
+        signal?.addEventListener('abort', abort, { once: true });
+        if (signal?.aborted) {
+            abort();
+            return;
+        }
+        child.send({ kind, root, request: { ...request, root: '.', path: leaf } }, error => {
+            if (error)
+                finish(computerFileError(error));
+        });
+    });
+}
+export async function readComputerFileSafely(request, signal, hooks) {
+    const root = await realpath(request.root).catch(error => { throw computerFileError(error); });
+    const target = await resolveComputerFilePath(root, request.path, false);
+    return execute('read', request, dirname(target), basename(target), signal, hooks);
+}
+export async function writeComputerFileSafely(request, signal, hooks) {
+    const root = await realpath(request.root).catch(error => { throw computerFileError(error); });
+    const target = await resolveComputerFilePath(root, request.path, request.mode === 'create');
+    return serialWrite(target, () => execute('write', request, dirname(target), basename(target), signal, hooks));
+}
+export async function listComputerDirSafely(request, signal, hooks) {
+    const root = await realpath(request.root).catch(error => { throw computerFileError(error); });
+    const target = await resolveComputerDirPath(root, request.path);
+    // Listing the workspace root pins the worker at the root itself; '' is the zero-component leaf.
+    const anchor = target === root ? root : dirname(target);
+    const leaf = target === root ? '' : basename(target);
+    const data = await execute('ls', request, anchor, leaf, signal, hooks);
+    return { ...data, path: request.path };
+}
+export async function createComputerDirSafely(request, signal, hooks) {
+    const root = await realpath(request.root).catch(error => { throw computerFileError(error); });
+    const plan = await resolveComputerDirCreatePath(root, request.path, request.parents);
+    const data = await execute('mkdir', request, plan.anchor, plan.missing.join('/'), signal, hooks);
+    return { ...data, path: request.path };
+}