@hachej/boring-execution 0.0.0-stage → 0.2.0

package/dist/remote-shell-window.js

@@ -0,0 +1,82 @@
+const encoder = new TextEncoder();
+const byteLength = (text) => encoder.encode(text).length;
+const newlines = (text) => { let count = 0; for (let at = text.indexOf('\n'); at !== -1; at = text.indexOf('\n', at + 1))
+    count++; return count; };
+/** Index where the remainder holds more than `maxBytes` UTF-8 bytes (the shortest such suffix), or -1 when the text is not longer. */
+function byteCut(text, maxBytes) {
+    let bytes = 0, index = text.length;
+    while (index > 0) {
+        const point = index >= 2 && text.charCodeAt(index - 1) >= 0xdc00 && text.charCodeAt(index - 1) <= 0xdfff && text.charCodeAt(index - 2) >= 0xd800 && text.charCodeAt(index - 2) <= 0xdbff ? 2 : 1;
+        index -= point;
+        bytes += byteLength(text.slice(index, index + point));
+        if (bytes > maxBytes)
+            return index === 0 ? -1 : index;
+    }
+    return -1;
+}
+/** Index where the remainder holds more than `maxLines` newlines (the shortest such suffix), or -1. */
+function lineCut(text, maxLines) {
+    let at = text.length;
+    for (let count = 0; count <= maxLines; count++) {
+        at = text.lastIndexOf('\n', at - 1);
+        if (at <= 0)
+            return -1;
+    }
+    return at;
+}
+/** Collects output, drops what the window cannot keep, and flushes no faster than `minIntervalMs`. */
+export function windowedOutput(window, emit) {
+    let text = '', stream = 'stdout', skip, last = 0;
+    let timer;
+    const omit = (omitted) => {
+        if (omitted === '')
+            return;
+        skip = { bytes: (skip?.bytes ?? 0) + byteLength(omitted), newlines: (skip?.newlines ?? 0) + newlines(omitted), endsWithNewline: omitted.endsWith('\n') };
+    };
+    const trim = () => {
+        const cuts = [byteCut(text, window.maxBytes), lineCut(text, window.maxLines)].filter(cut => cut > 0);
+        if (cuts.length === 0)
+            return;
+        const cut = Math.max(...cuts);
+        omit(text.slice(0, cut));
+        text = text.slice(cut);
+    };
+    const flush = () => {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+        trim();
+        if (text === '' && skip === undefined)
+            return;
+        const chunk = { text, stream, ...(skip === undefined ? {} : { skipped: skip }) };
+        text = '';
+        skip = undefined;
+        last = Date.now();
+        emit(chunk);
+    };
+    return {
+        push(chunk, info) {
+            if (info.skipped !== undefined) {
+                omit(text);
+                text = '';
+                skip = { bytes: (skip?.bytes ?? 0) + info.skipped.bytes, newlines: (skip?.newlines ?? 0) + info.skipped.newlines, endsWithNewline: info.skipped.endsWithNewline };
+            }
+            text += chunk;
+            stream = info.stream;
+            trim();
+            const wait = last + window.minIntervalMs - Date.now();
+            if (wait <= 0)
+                flush();
+            else
+                timer ??= setTimeout(() => { timer = undefined; try {
+                    flush();
+                }
+                catch { /* the transport closed */ } }, wait);
+        },
+        /** Deliver what is buffered before the terminal result. */
+        finish: flush,
+        cancel() { if (timer !== undefined)
+            clearTimeout(timer); timer = undefined; text = ''; skip = undefined; },
+    };
+}

package/dist/remote-shell.d.ts

@@ -0,0 +1,15 @@
+import type { Shell } from '@earendil-works/pi-durable/env';
+import type { WorkspaceIdentity, WorkspaceLease } from './contracts.js';
+export { createRemoteShellHandler } from './remote-shell-handler.js';
+export type { RemoteShellAccess, RemoteShellHandlerOptions } from './remote-shell-handler.js';
+export interface RemoteShellOptions {
+    readonly identity: WorkspaceIdentity;
+    readonly endpoint: string | URL;
+    /** Trusted authenticated transport. It must honor redirect:error and must not retry command requests. */
+    readonly fetch: (request: Request) => Promise<Response>;
+    readonly maxRequestBytes?: number;
+    readonly maxFrameBytes?: number;
+}
+/** Borrow the remote workspace. Cleanup cancels this lease's transports, not the provider or another lease. */
+export declare function createRemoteShellLease(options: RemoteShellOptions): WorkspaceLease<Shell>;
+//# sourceMappingURL=remote-shell.d.ts.map

package/dist/remote-shell.js

@@ -0,0 +1,127 @@
+import { awaitWithContext, withAbortSignal } from '@earendil-works/chord/context';
+import { ExecutionError, err } from '@earendil-works/pi-durable/env';
+import { contentType, frame, identity, nativeVersion, positiveLimit, sameIdentity, schema, version, wireOptions } from './remote-shell-protocol.js';
+import { randomUUID } from '@hachej/boring-files/platform';
+import { shellCommand } from './fs-readers.js';
+export { createRemoteShellHandler } from './remote-shell-handler.js';
+/** Borrow the remote workspace. Cleanup cancels this lease's transports, not the provider or another lease. */
+export function createRemoteShellLease(options) {
+    const selected = identity(options.identity), endpoint = new URL(options.endpoint);
+    if (!['https:', 'http:'].includes(endpoint.protocol) || endpoint.username || endpoint.password || endpoint.hash)
+        throw new TypeError('Expected an HTTP endpoint without URL credentials or fragment');
+    const fetch = options.fetch;
+    const maxRequestBytes = positiveLimit(options.maxRequestBytes ?? 65_536), maxFrameBytes = positiveLimit(options.maxFrameBytes ?? 1_048_576);
+    const active = new Set();
+    let closed = false;
+    const release = async () => { closed = true; for (const request of active)
+        request.abort(); active.clear(); };
+    const environment = {
+        cleanup: release,
+        exec: async (command, options, context) => {
+            if (closed)
+                return err(new ExecutionError('shell_unavailable', 'Remote shell lease is closed'));
+            if (context.abortSignal?.aborted)
+                return err(new ExecutionError('aborted', 'Command aborted before dispatch'));
+            const onOutput = options?.onOutput;
+            if (onOutput !== undefined && typeof onOutput !== 'function')
+                return err(new ExecutionError('callback_error', 'Expected a synchronous output callback'));
+            const requestId = randomUUID(), abort = new AbortController();
+            const signal = context.abortSignal ? AbortSignal.any([abort.signal, context.abortSignal]) : abort.signal;
+            const local = withAbortSignal(signal, context);
+            let reader;
+            let dispatched = false;
+            active.add(abort);
+            try {
+                const { onOutput: _callback, ...arguments_ } = options ?? {};
+                const body = JSON.stringify({ schema, version, nativeVersion, requestId, identity: selected, command: shellCommand(command), options: wireOptions(arguments_), output: onOutput !== undefined });
+                if ((typeof command !== 'string' && !Array.isArray(command)) || new TextEncoder().encode(body).byteLength > maxRequestBytes)
+                    return err(new ExecutionError('shell_unavailable', 'Remote shell request is invalid or exceeds its byte limit'));
+                const request = new Request(endpoint, { method: 'POST', headers: { 'content-type': 'application/json' }, body, redirect: 'error', signal });
+                dispatched = true;
+                const pending = fetch(request);
+                void pending.then(response => { if (signal?.aborted)
+                    void response.body?.cancel().catch(() => { }); }, () => { });
+                const response = await awaitWithContext(pending, local);
+                if (response.redirected || response.status !== 200 || response.headers.get('content-type')?.split(';')[0]?.trim() !== contentType || !response.body) {
+                    void response.body?.cancel().catch(() => { });
+                    return err(new ExecutionError('unknown', `Remote shell response refused or unavailable (${response.status}); command outcome is unconfirmed`));
+                }
+                reader = response.body.getReader();
+                let sequence = 0, header = false, terminal;
+                for await (const value of frames(reader, local, maxFrameBytes)) {
+                    if (signal.aborted)
+                        throw new Error('Remote shell observation aborted');
+                    const current = frame(value, requestId, sequence++);
+                    if (terminal !== undefined)
+                        throw new Error('Data after terminal result');
+                    if (!header) {
+                        if (current.type !== 'header' || !sameIdentity(current.identity, selected))
+                            throw new Error('Remote workspace identity mismatch');
+                        header = true;
+                    }
+                    else if (current.type === 'output') {
+                        try {
+                            onOutput?.(current.text, context, current.skipped === undefined ? { stream: current.stream } : { stream: current.stream, skipped: current.skipped });
+                        }
+                        catch {
+                            return err(new ExecutionError('callback_error', 'Local output callback failed; remote termination is unconfirmed'));
+                        }
+                    }
+                    else if (current.type === 'result')
+                        terminal = current.result;
+                    else
+                        throw new Error('Duplicate remote shell header');
+                }
+                if (signal.aborted || !header || terminal === undefined)
+                    throw new Error('Missing terminal acknowledgement');
+                return terminal;
+            }
+            catch {
+                return err(new ExecutionError(signal.aborted ? 'aborted' : dispatched ? 'unknown' : 'shell_unavailable', dispatched
+                    ? 'Remote shell observation ended; prior effects may remain and remote termination is unconfirmed'
+                    : 'Invalid remote shell request; command was not dispatched'));
+            }
+            finally {
+                abort.abort();
+                active.delete(abort);
+                if (reader) {
+                    void reader.cancel().catch(() => { });
+                    reader.releaseLock();
+                }
+            }
+        },
+    };
+    return { identity: selected, environment, ownership: 'borrowed', release };
+}
+async function* frames(reader, context, limit) {
+    let pieces = [], length = 0;
+    while (true) {
+        const item = await awaitWithContext(reader.read(), context);
+        if (item.done) {
+            if (length !== 0)
+                throw new Error('Truncated remote shell frame');
+            return;
+        }
+        let start = 0;
+        while (start < item.value.byteLength) {
+            const newline = item.value.indexOf(10, start), end = newline === -1 ? item.value.byteLength : newline;
+            const piece = item.value.subarray(start, end);
+            length += piece.byteLength;
+            if (length > limit)
+                throw new Error('Remote shell frame exceeds its byte limit');
+            pieces.push(piece);
+            if (newline === -1)
+                break;
+            const bytes = new Uint8Array(length);
+            let offset = 0;
+            for (const part of pieces) {
+                bytes.set(part, offset);
+                offset += part.byteLength;
+            }
+            pieces = [];
+            length = 0;
+            yield JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+            start = newline + 1;
+        }
+    }
+}

package/dist/virtual-filesystem.d.ts

@@ -0,0 +1,67 @@
+import { InMemoryFs } from 'just-bash';
+import type { IFileSystem, FileContent, MkdirOptions, RmOptions, CpOptions, BufferEncoding, FsStat, CreateExclusiveOptions } from 'just-bash';
+type ReadFileOptions = Exclude<Parameters<IFileSystem['readFile']>[1], string | undefined>;
+type WriteFileOptions = Exclude<Parameters<IFileSystem['writeFile']>[2], string | undefined>;
+type DirentEntry = Awaited<ReturnType<NonNullable<IFileSystem['readdirWithFileTypes']>>>[number];
+import type { FileSystem } from '@earendil-works/pi-durable/env';
+export { MAX_ERROR_CHARS, boundedMessage } from './bounded-error.js';
+/** What the shell and the native environment need from the files under them: just-bash's interface plus an atomic file replace. */
+export type VirtualFiles = IFileSystem & {
+    readonly replaceFile: (source: string, destination: string) => Promise<void>;
+    readonly createExclusive: (path: string, options: CreateExclusiveOptions) => Promise<void>;
+};
+/**
+ * just-bash's file interface over a Pi `FileSystem` (for example `@hachej/boring-files/sqlite-filesystem`), so the shell, Git and the native
+ * environment work on the very files the workspace provider reads and writes: one view, no copy. That file system has regular files
+ * and directories only: links are refused, `chmod` changes nothing (files report 0644, directories 0755) and `utimes` sets the
+ * modification time to now.
+ */
+export declare class FileSystemView implements VirtualFiles {
+    private readonly fs;
+    constructor(fs: FileSystem);
+    private stats;
+    readFile(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
+    readFileBuffer(path: string): Promise<Uint8Array>;
+    writeFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
+    appendFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FsStat>;
+    lstat(path: string): Promise<FsStat>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    readdir(path: string): Promise<string[]>;
+    readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
+    rm(path: string, options?: RmOptions): Promise<void>;
+    cp(source: string, destination: string, options?: CpOptions): Promise<void>;
+    mv(source: string, destination: string): Promise<void>;
+    replaceFile(source: string, destination: string): Promise<void>;
+    createExclusive(path: string, options: CreateExclusiveOptions): Promise<void>;
+    resolvePath(base: string, path: string): string;
+    /** Not enumerable synchronously over an asynchronous file system; nothing in the shell needs it. */
+    getAllPaths(): string[];
+    chmod(path: string): Promise<void>;
+    symlink(_target: string, path: string): Promise<void>;
+    link(_source: string, path: string): Promise<void>;
+    readlink(path: string): Promise<string>;
+    realpath(path: string): Promise<string>;
+    utimes(path: string): Promise<void>;
+}
+/** Resolve missing leaves and existing aliases through public upstream filesystem operations. */
+export declare function mutationPath(fs: IFileSystem, input: string, parents: boolean, followFinal: boolean): Promise<string>;
+/** Upstream owns storage. Mutating methods resolve aliases consistently with upstream readers. */
+export declare class VirtualFileSystem extends InMemoryFs {
+    private requireFileTarget;
+    writeFile(path: string, content: FileContent, options?: Parameters<InMemoryFs['writeFile']>[2]): Promise<void>;
+    appendFile(path: string, content: FileContent, options?: Parameters<InMemoryFs['writeFile']>[2]): Promise<void>;
+    mkdir(path: string, options?: MkdirOptions): Promise<void>;
+    rm(path: string, options?: RmOptions): Promise<void>;
+    createExclusive(path: string, options: Parameters<InMemoryFs['createExclusive']>[1]): Promise<void>;
+    mv(_source: string, _destination: string): Promise<void>;
+    /** Move one regular file over a file or a missing path in a single synchronous upstream step, so a reader sees the old or the new bytes. */
+    replaceFile(source: string, destination: string): Promise<void>;
+    cp(source: string, destination: string, options?: CpOptions): Promise<void>;
+    symlink(target: string, path: string): Promise<void>;
+    link(_source: string, _destination: string): Promise<void>;
+    chmod(path: string, mode: number): Promise<void>;
+    utimes(path: string, atime: Date, mtime: Date): Promise<void>;
+}
+//# sourceMappingURL=virtual-filesystem.d.ts.map

package/dist/virtual-filesystem.js

@@ -0,0 +1,218 @@
+import { posix } from 'node:path';
+import { InMemoryFs } from 'just-bash';
+import { BACKGROUND_CONTEXT } from '@earendil-works/chord/context';
+import { boundedMessage } from './bounded-error.js';
+export { MAX_ERROR_CHARS, boundedMessage } from './bounded-error.js';
+const errno = {
+    not_found: 'ENOENT', not_directory: 'ENOTDIR', is_directory: 'EISDIR', permission_denied: 'EACCES', invalid: 'EINVAL', not_supported: 'ENOTSUP', aborted: 'ECANCELED', unknown: 'EIO',
+};
+async function value(pending) {
+    const result = await pending;
+    if (result.ok)
+        return result.value;
+    // Shells and Git read the POSIX code from the start of the message.
+    const message = boundedMessage(result.error);
+    throw new Error(/^E[A-Z]+\b/.test(message) ? message : `${errno[result.error.code]}: ${message}`, { cause: result.error });
+}
+const encodingOf = (options) => (typeof options === 'string' ? options : options?.encoding) ?? 'utf8';
+const latin1 = (bytes) => Array.from(bytes, byte => String.fromCharCode(byte)).join('');
+function decode(bytes, encoding) {
+    if (encoding === 'utf8' || encoding === 'utf-8' || encoding === null)
+        return new TextDecoder().decode(bytes);
+    if (encoding === 'base64')
+        return btoa(latin1(bytes));
+    if (encoding === 'hex')
+        return Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
+    return encoding === 'ascii' ? latin1(bytes.map(byte => byte & 0x7f)) : latin1(bytes);
+}
+function encode(content, encoding) {
+    if (typeof content !== 'string')
+        return Uint8Array.from(content);
+    if (encoding === 'utf8' || encoding === 'utf-8')
+        return new TextEncoder().encode(content);
+    if (encoding === 'base64')
+        return Uint8Array.from(atob(content), char => char.charCodeAt(0));
+    if (encoding === 'hex')
+        return Uint8Array.from(content.match(/../g) ?? [], pair => Number.parseInt(pair, 16));
+    return Uint8Array.from(content, char => char.charCodeAt(0) & 0xff);
+}
+/**
+ * just-bash's file interface over a Pi `FileSystem` (for example `@hachej/boring-files/sqlite-filesystem`), so the shell, Git and the native
+ * environment work on the very files the workspace provider reads and writes: one view, no copy. That file system has regular files
+ * and directories only: links are refused, `chmod` changes nothing (files report 0644, directories 0755) and `utimes` sets the
+ * modification time to now.
+ */
+export class FileSystemView {
+    fs;
+    constructor(fs) {
+        this.fs = fs;
+    }
+    stats = async (path) => {
+        const info = await value(this.fs.fileInfo(path, BACKGROUND_CONTEXT));
+        const directory = info.kind === 'directory';
+        return { isFile: !directory, isDirectory: directory, isSymbolicLink: false, mode: directory ? 0o755 : 0o644, size: info.size, mtime: new Date(info.mtimeMs) };
+    };
+    async readFile(path, options) { return decode(await this.readFileBuffer(path), encodingOf(options)); }
+    readFileBuffer(path) { return value(this.fs.readBinaryFile(path, BACKGROUND_CONTEXT)); }
+    writeFile(path, content, options) { return value(this.fs.writeFile(path, encode(content, encodingOf(options) ?? 'utf8'), BACKGROUND_CONTEXT)); }
+    appendFile(path, content, options) { return value(this.fs.appendFile(path, encode(content, encodingOf(options) ?? 'utf8'), BACKGROUND_CONTEXT)); }
+    exists(path) { return value(this.fs.exists(path, BACKGROUND_CONTEXT)); }
+    stat(path) { return this.stats(path); }
+    lstat(path) { return this.stats(path); }
+    mkdir(path, options) { return value(this.fs.createDir(path, { recursive: options?.recursive === true }, BACKGROUND_CONTEXT)); }
+    async readdir(path) { return (await value(this.fs.listDir(path, BACKGROUND_CONTEXT))).map(entry => entry.name).sort(); }
+    async readdirWithFileTypes(path) {
+        return (await value(this.fs.listDir(path, BACKGROUND_CONTEXT))).sort((a, b) => a.name < b.name ? -1 : 1)
+            .map(entry => ({ name: entry.name, isFile: entry.kind === 'file', isDirectory: entry.kind === 'directory', isSymbolicLink: entry.kind === 'symlink' }));
+    }
+    rm(path, options) { return value(this.fs.remove(path, { recursive: options?.recursive === true, force: options?.force === true }, BACKGROUND_CONTEXT)); }
+    async cp(source, destination, options) {
+        if (!(await this.stats(source)).isDirectory)
+            return this.writeFile(destination, await this.readFileBuffer(source));
+        if (!options?.recursive)
+            throw new Error(`EISDIR: copying a directory needs recursive, '${source}'`);
+        await this.mkdir(destination, { recursive: true });
+        for (const name of await this.readdir(source))
+            await this.cp(posix.join(source, name), posix.join(destination, name), options);
+    }
+    mv(source, destination) { return this.replaceFile(source, destination); }
+    replaceFile(source, destination) { return value(this.fs.renameFile(source, destination, BACKGROUND_CONTEXT)); }
+    async createExclusive(path, options) {
+        if (await this.exists(path))
+            throw new Error(`EEXIST: file already exists, '${path}'`);
+        await (options.directory ? this.mkdir(path) : this.writeFile(path, new Uint8Array()));
+    }
+    resolvePath(base, path) { return posix.resolve(base, path); }
+    /** Not enumerable synchronously over an asynchronous file system; nothing in the shell needs it. */
+    getAllPaths() { return []; }
+    async chmod(path) { await this.stats(path); }
+    async symlink(_target, path) { throw new Error(`ENOTSUP: symbolic links are not supported by this file system, '${path}'`); }
+    async link(_source, path) { throw new Error(`ENOTSUP: hard links are not supported by this file system, '${path}'`); }
+    async readlink(path) { await this.stats(path); throw new Error(`EINVAL: not a symbolic link, '${path}'`); }
+    realpath(path) { return value(this.fs.canonicalPath(path, BACKGROUND_CONTEXT)); }
+    async utimes(path) { if (!(await this.stats(path)).isDirectory)
+        await this.appendFile(path, new Uint8Array()); }
+}
+/** Resolve missing leaves and existing aliases through public upstream filesystem operations. */
+export async function mutationPath(fs, input, parents, followFinal) {
+    if (!input.startsWith('/') || input.includes('\0'))
+        throw new Error('EINVAL: an absolute virtual path is required');
+    let parts = posix.normalize(input).split('/').filter(Boolean), current = '/', links = 0;
+    while (parts.length) {
+        const part = parts.shift();
+        if (part === undefined)
+            break;
+        const candidate = posix.join(current, part), final = parts.length === 0;
+        let stat;
+        try {
+            stat = await fs.lstat(candidate);
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !/\bENOENT\b/.test(error.message))
+                throw error;
+            if (final)
+                return candidate;
+            if (!parents)
+                throw error;
+            await fs.mkdir(candidate, { recursive: true });
+            current = candidate;
+            continue;
+        }
+        if (stat.isSymbolicLink && (!final || followFinal)) {
+            if (++links > 40)
+                throw new Error('ELOOP: too many symbolic links');
+            parts = posix.resolve(current, await fs.readlink(candidate), ...parts).split('/').filter(Boolean);
+            current = '/';
+            continue;
+        }
+        if (!final && !stat.isDirectory)
+            throw new Error('ENOTDIR: path ancestor is not a directory');
+        current = candidate;
+    }
+    return current;
+}
+/** Upstream owns storage. Mutating methods resolve aliases consistently with upstream readers. */
+export class VirtualFileSystem extends InMemoryFs {
+    async requireFileTarget(path) {
+        try {
+            if ((await this.lstat(path)).isDirectory)
+                throw new Error('EISDIR: write target is a directory');
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !/\bENOENT\b/.test(error.message))
+                throw error;
+        }
+    }
+    async writeFile(path, content, options) {
+        const bytes = typeof content === 'string' ? content : Uint8Array.from(content);
+        const target = await mutationPath(this, path, true, true);
+        await this.requireFileTarget(target);
+        await super.writeFile(target, bytes, options);
+    }
+    async appendFile(path, content, options) {
+        const bytes = typeof content === 'string' ? content : Uint8Array.from(content);
+        const target = await mutationPath(this, path, true, true);
+        await this.requireFileTarget(target);
+        await super.appendFile(target, bytes, options);
+    }
+    async mkdir(path, options) {
+        const target = await mutationPath(this, path, options?.recursive === true, options?.recursive === true);
+        try {
+            if (!(await this.lstat(target)).isDirectory)
+                throw new Error('ENOTDIR: mkdir target is not a directory');
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !/\bENOENT\b/.test(error.message))
+                throw error;
+        }
+        await super.mkdir(target, options);
+    }
+    async rm(path, options) {
+        let target;
+        try {
+            target = await mutationPath(this, path, false, false);
+        }
+        catch (error) {
+            if (options?.force && error instanceof Error && /\bENOENT\b/.test(error.message))
+                return;
+            throw error;
+        }
+        await super.rm(target, options);
+    }
+    async createExclusive(path, options) {
+        await super.createExclusive(await mutationPath(this, path, false, false), options);
+    }
+    async mv(_source, _destination) {
+        throw new Error('ENOTSUP: backing move does not preserve native rename semantics');
+    }
+    /** Move one regular file over a file or a missing path in a single synchronous upstream step, so a reader sees the old or the new bytes. */
+    async replaceFile(source, destination) {
+        const from = await mutationPath(this, source, false, false), to = await mutationPath(this, destination, false, true);
+        if (!(await this.lstat(from)).isFile)
+            throw new Error('ENOTSUP: only a regular file can be replaced by rename');
+        await this.requireFileTarget(to);
+        await InMemoryFs.prototype.mv.call(this, from, to);
+    }
+    async cp(source, destination, options) {
+        const from = await mutationPath(this, source, false, false), to = await mutationPath(this, destination, false, true);
+        if ((await this.lstat(from)).isDirectory)
+            throw new Error('ENOTSUP: recursive directory copy is not qualified');
+        if (await this.exists(to)) {
+            if ((await this.stat(to)).isDirectory)
+                throw new Error('EISDIR: copy destination must be a file');
+        }
+        await super.cp(from, to, options);
+    }
+    async symlink(target, path) {
+        await super.symlink(target, await mutationPath(this, path, false, false));
+    }
+    async link(_source, _destination) {
+        throw new Error('ENOTSUP: hard links do not preserve shared file identity');
+    }
+    async chmod(path, mode) {
+        await super.chmod(await mutationPath(this, path, false, true), mode);
+    }
+    async utimes(path, atime, mtime) {
+        await super.utimes(await mutationPath(this, path, false, true), atime, mtime);
+    }
+}

package/dist/virtual-git.d.ts

@@ -0,0 +1,60 @@
+import type { Bash, IFileSystem, BufferEncoding } from 'just-bash';
+import type { createGitRepository } from '@hachej/boring-files/git';
+/** isomorphic-git I/O over the selected just-bash view; no second checkout or native Git. */
+export declare function createVirtualGitFs(filesystem: IFileSystem): {
+    filesystem: IFileSystem;
+    promises: {
+        readFile: (path: string, options?: BufferEncoding | {
+            encoding?: BufferEncoding;
+        } | undefined) => Promise<string | Uint8Array<ArrayBuffer>>;
+        writeFile: (path: string, bytes: string | Uint8Array<ArrayBufferLike>) => Promise<void>;
+        unlink: (path: string) => Promise<void>;
+        readdir: (path: string) => Promise<string[]>;
+        mkdir: (path: string, options?: number | {
+            recursive?: boolean;
+        } | undefined) => Promise<void>;
+        rmdir: (path: string) => Promise<void>;
+        stat: (path: string) => Promise<{
+            isFile: () => boolean;
+            isDirectory: () => boolean;
+            isSymbolicLink: () => boolean;
+            mode: number;
+            mtimeMs: number;
+            ctime: Date;
+            ctimeMs: number;
+            uid: number;
+            gid: number;
+            dev: number | bigint;
+            ino: number;
+            size: number;
+            mtime: Date;
+            identity?: string;
+        }>;
+        lstat: (path: string) => Promise<{
+            isFile: () => boolean;
+            isDirectory: () => boolean;
+            isSymbolicLink: () => boolean;
+            mode: number;
+            mtimeMs: number;
+            ctime: Date;
+            ctimeMs: number;
+            uid: number;
+            gid: number;
+            dev: number | bigint;
+            ino: number;
+            size: number;
+            mtime: Date;
+            identity?: string;
+        }>;
+        readlink: (path: string) => Promise<string>;
+        symlink: (target: string, path: string) => Promise<void>;
+        chmod: (path: string, mode: number) => Promise<void>;
+    };
+};
+export interface VirtualGitOptions {
+    readonly bash: Bash;
+    readonly repository: ReturnType<typeof createGitRepository<ReturnType<typeof createVirtualGitFs>>>;
+}
+/** Bind one repository service to its selected backing and root cwd. */
+export declare function installVirtualGitCommand({ bash, repository }: VirtualGitOptions): void;
+//# sourceMappingURL=virtual-git.d.ts.map