@hachej/boring-execution 0.0.0-stage → 0.2.1

package/dist/virtual-git.js

@@ -0,0 +1,116 @@
+import { defineCommand } from 'just-bash';
+import { posix } from 'node:path';
+import { boundedMessage, mutationPath } from './virtual-filesystem.js';
+/** isomorphic-git I/O over the selected just-bash view; no second checkout or native Git. */
+export function createVirtualGitFs(filesystem) {
+    const wrap = (operation) => async (...args) => {
+        try {
+            return await operation(...args);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                const code = /\b(ENOENT|EEXIST|ENOTDIR|EISDIR|ENOTEMPTY|EACCES|EPERM|EINVAL)\b/.exec(error.message)?.[1];
+                if (code)
+                    throw Object.assign(new Error(error.message, { cause: error }), { code });
+            }
+            throw error;
+        }
+    };
+    // Racy-clean guard: isomorphic-git compares whole seconds, so a same-size edit in the second of its `add` looks clean. The
+    // reported inode folds in the millisecond mtime, and is unique per call while the file is fresh, so such entries are rehashed.
+    let fresh = 0;
+    const stat = (value) => {
+        const mtimeMs = value.mtime.getTime(), racy = Date.now() - mtimeMs < 1000;
+        return {
+            ...value, isFile: () => value.isFile, isDirectory: () => value.isDirectory, isSymbolicLink: () => value.isSymbolicLink,
+            mode: value.isSymbolicLink ? 0o120000 | (value.mode & 0o777) : value.mode,
+            mtimeMs, ctime: value.mtime, ctimeMs: mtimeMs, uid: 0, gid: 0, dev: value.dev ?? 0,
+            ino: racy ? 0x80000000 + (++fresh % 0x7fffffff) : (Number(value.ino ?? 0) * 31 + mtimeMs) % 0x80000000,
+        };
+    };
+    return { filesystem, promises: {
+            readFile: wrap(async (path, options) => {
+                const encoding = typeof options === 'string' ? options : options?.encoding;
+                return encoding ? filesystem.readFile(path, encoding) : Uint8Array.from(await filesystem.readFileBuffer(path));
+            }),
+            writeFile: wrap(async (path, bytes) => {
+                const captured = typeof bytes === 'string' ? bytes : Uint8Array.from(bytes);
+                await filesystem.writeFile(await mutationPath(filesystem, path, false, true), captured);
+            }),
+            unlink: wrap(async (path) => {
+                path = posix.join(await filesystem.realpath(posix.dirname(path)), posix.basename(path));
+                if ((await filesystem.lstat(path)).isDirectory)
+                    throw new Error('EISDIR: unlink requires a file');
+                await filesystem.rm(path);
+            }),
+            readdir: wrap((path) => filesystem.readdir(path)),
+            mkdir: wrap(async (path, options) => {
+                const selected = typeof options === 'object' ? options : {};
+                await filesystem.mkdir(await mutationPath(filesystem, path, selected.recursive === true, false), selected);
+            }),
+            rmdir: wrap(async (path) => {
+                path = posix.join(await filesystem.realpath(posix.dirname(path)), posix.basename(path));
+                if (!(await filesystem.lstat(path)).isDirectory)
+                    throw new Error('ENOTDIR: rmdir requires a directory');
+                await filesystem.rm(path);
+            }),
+            stat: wrap(async (path) => stat(await filesystem.stat(path))),
+            lstat: wrap(async (path) => stat(await filesystem.lstat(path))),
+            readlink: wrap((path) => filesystem.readlink(path)),
+            symlink: wrap((target, path) => filesystem.symlink(target, path)),
+            chmod: wrap((path, mode) => filesystem.chmod(path, mode)),
+        } };
+}
+/** Bind one repository service to its selected backing and root cwd. */
+export function installVirtualGitCommand({ bash, repository }) {
+    if (bash.fs !== repository.fs.filesystem)
+        throw new TypeError('Git command requires its bound filesystem');
+    bash.registerCommand(defineCommand('git', async (args, context) => {
+        if (context.cwd !== repository.directory) {
+            return { stdout: '', stderr: 'Git command requires its bound filesystem and repository cwd\n', exitCode: 126 };
+        }
+        const [command, ...rest] = args;
+        const signal = context.signal;
+        let stdout = '';
+        try {
+            if (command === 'init' && rest.length === 0) {
+                await repository.init(signal);
+                stdout = 'Initialized virtual Git repository\n';
+            }
+            else if (command === 'status' && rest.length === 0) {
+                stdout = JSON.stringify(await repository.status(signal)) + '\n';
+            }
+            else if (command === 'add' && rest.length === 1 && rest[0] && !rest[0].startsWith('-')) {
+                await repository.add(rest[0], signal);
+            }
+            else if (command === 'rm' && rest.length === 2 && rest[0] === '--cached' && rest[1]) {
+                await repository.remove(rest[1], signal);
+            }
+            else if (command === 'commit' && rest.length === 2 && rest[0] === '-m' && rest[1]) {
+                stdout = await repository.commit(rest[1], signal) + '\n';
+            }
+            else if (command === 'log' && rest.length === 0) {
+                stdout = JSON.stringify(await repository.log(signal)) + '\n';
+            }
+            else if (command === 'branch' && rest.length === 0) {
+                stdout = (await repository.branches(signal)).join('\n') + '\n';
+            }
+            else if (command === 'branch' && rest.length === 1 && rest[0] && !rest[0].startsWith('-')) {
+                await repository.branch(rest[0], signal);
+            }
+            else if (command === 'checkout' && rest.length === 1 && rest[0] && !rest[0].startsWith('-')) {
+                await repository.checkout(rest[0], signal);
+            }
+            else if (command === 'diff' && (rest.length === 0 || rest.length === 1 && rest[0] === '--cached')) {
+                stdout = JSON.stringify(await repository.diff(rest.length ? { kind: 'tree', ref: 'HEAD' } : { kind: 'index' }, rest.length ? { kind: 'index' } : { kind: 'worktree' }, signal)) + '\n';
+            }
+            else {
+                return { stdout: '', stderr: 'Unsupported virtual Git command or arguments\n', exitCode: 126 };
+            }
+            return { stdout, stderr: '', exitCode: 0 };
+        }
+        catch (error) {
+            return { stdout, stderr: `${boundedMessage(error)}\n`, exitCode: 1 };
+        }
+    }));
+}

package/dist/virtual-sqlite.d.ts

@@ -0,0 +1,42 @@
+import type { Context } from '@earendil-works/chord';
+import type { ExecutionEnv, FileSystem } from '@earendil-works/pi-durable/env';
+import { createGitRepository } from '@hachej/boring-files/git';
+import type { GitOperation } from '@hachej/boring-files/git';
+import { createVirtualGitFs } from './virtual-git.js';
+export interface VirtualRepositoryOptions {
+    /** Where the files live, for example `openSqliteFileSystem({ connection, workspace, cwd: root })` from `@hachej/boring-files/sqlite-filesystem`. */
+    readonly fs: FileSystem;
+    /** Absolute directory of the repository inside the file system. Default `/repo`. */
+    readonly root?: string;
+    /** Files of a new repository, by path relative to `root`. They are committed as `seedMessage`; ignored when the repository exists. */
+    readonly seed?: Readonly<Record<string, string>>;
+    readonly seedMessage?: string;
+    /** Commit author for `repository.commit` (the shell's `git commit` too). */
+    readonly author?: {
+        readonly name: string;
+        readonly email: string;
+    };
+    /** Context for acquiring the workspace (a host context such as `BACKGROUND_CONTEXT`). */
+    readonly context: Context;
+    /** The host's git policy for `repository` (and the shell's `git`). Default: every operation is allowed. */
+    readonly authorize?: (operation: GitOperation) => boolean | Promise<boolean>;
+    /** Provider id recorded in the workspace identity. Default `virtual-sqlite`. */
+    readonly providerId?: string;
+}
+type Repository = ReturnType<typeof createGitRepository<ReturnType<typeof createVirtualGitFs>>>;
+/**
+ * One repository, one working view: Pi's native `env` for reading, listing, writing and running commands (its bash has
+ * `git`), and the `@hachej/boring-files/git` service bound to the same files. There is deliberately no second file or shell API.
+ */
+export interface VirtualRepository {
+    readonly root: string;
+    /** Pi's native `ExecutionEnv` over the repository: native tools use it; its `exec` shell has the `git` command. */
+    readonly env: ExecutionEnv;
+    readonly repository: Repository;
+    /** Release the workspace. The files stay where `fs` keeps them. */
+    close(): Promise<void>;
+}
+/** Open the repository in `fs`, or create it from `seed` when `root` has no `.git` yet. */
+export declare function openVirtualRepository(options: VirtualRepositoryOptions): Promise<VirtualRepository>;
+export {};
+//# sourceMappingURL=virtual-sqlite.d.ts.map

package/dist/virtual-sqlite.js

@@ -0,0 +1,50 @@
+// One git repository in a virtual workspace (a browser tab, or Node): a just-bash workspace with isomorphic-git whose files live in
+// SQLite, through the Pi `FileSystem` of `@hachej/boring-files/sqlite-filesystem` (in a browser over `openBrowserSqliteConnection`). Every
+// write lands in SQLite as it happens: there is no copy in memory and nothing to save. Pi's native tools reach it through a native
+// `ExecutionEnv` whose bash also has the `git` command bound to the same repository. Nothing here is a second file or shell API:
+// `env` is Pi's and `repository` is `@hachej/boring-files/git`'s.
+import { posix } from 'node:path';
+import { createGitRepository } from '@hachej/boring-files/git';
+import { createVirtualWorkspace } from './virtual.js';
+import { createVirtualGitFs, installVirtualGitCommand } from './virtual-git.js';
+/** Open the repository in `fs`, or create it from `seed` when `root` has no `.git` yet. */
+export async function openVirtualRepository(options) {
+    const { context } = options;
+    const root = posix.normalize(options.root ?? '/repo').replace(/(.)\/$/, '$1');
+    if (!root.startsWith('/') || root === '/')
+        throw new TypeError('root must be an absolute directory such as /repo');
+    // Every shell of the workspace, the native `exec`'s included, gets `git` bound to the one repository on the same files.
+    let repository;
+    const workspace = createVirtualWorkspace({ providerId: options.providerId ?? 'virtual-sqlite', fs: options.fs,
+        onBash: bash => { if (repository)
+            installVirtualGitCommand({ bash, repository }); } });
+    const filesystem = workspace.filesystem;
+    await filesystem.mkdir(root, { recursive: true });
+    const fresh = !await filesystem.exists(posix.join(root, '.git'));
+    if (fresh) {
+        for (const [path, text] of Object.entries(options.seed ?? {})) {
+            const absolute = posix.join(root, path);
+            await filesystem.mkdir(posix.dirname(absolute), { recursive: true });
+            await filesystem.writeFile(absolute, text);
+        }
+    }
+    const lease = await workspace.acquire({ operationId: 'virtual-sqlite', input: { cwd: root } }, context);
+    repository = createGitRepository({ fs: createVirtualGitFs(filesystem), directory: root, authorize: options.authorize ?? (() => true),
+        author: options.author ?? { name: 'Agent', email: 'agent@example.invalid' } });
+    if (fresh) {
+        await repository.init();
+        for (const path of Object.keys(options.seed ?? {}))
+            await repository.add(path);
+        if (Object.keys(options.seed ?? {}).length)
+            await repository.commit(options.seedMessage ?? 'Initial commit');
+    }
+    return {
+        root, env: lease.environment, repository,
+        async close() { try {
+            await lease.release(context);
+        }
+        finally {
+            workspace.dispose();
+        } },
+    };
+}

package/dist/virtual.d.ts

@@ -0,0 +1,34 @@
+import { Bash } from 'just-bash';
+import type { BashOptions, InitialFiles, IFileSystem, InMemoryFs } from 'just-bash';
+import type { ExecutionEnv, FileSystem } from '@earendil-works/pi-durable/env';
+import type { WorkspaceProvider } from './contracts.js';
+export { MAX_ERROR_CHARS } from './virtual-filesystem.js';
+export interface VirtualWorkspaceOptions {
+    readonly providerId: string;
+    readonly files?: InitialFiles;
+    readonly storage?: ConstructorParameters<typeof InMemoryFs>[1];
+    /**
+     * Keep the files in this Pi `FileSystem` (for example `@hachej/boring-files/sqlite-filesystem`) instead of memory: the shell, the native
+     * environment and a workspace provider over the same `fs` then see the same files. Not combined with `files` or `storage`.
+     */
+    readonly fs?: FileSystem;
+    readonly bash?: Omit<BashOptions, 'fs' | 'files' | 'cwd' | 'python'>;
+    /**
+     * Offer `python3` and `python` in the shell: just-bash's CPython compiled to WebAssembly. Off by default. Node only (refused elsewhere,
+     * for example in a browser worker); it loads a ~10 MB runtime on first use and its memory is not contained like the shell's limits.
+     */
+    readonly python?: boolean;
+    /** Called with every shell this workspace creates, the native `exec`'s included, for example to install `git` bound to it. */
+    readonly onBash?: (bash: Bash) => void;
+}
+export interface VirtualWorkspace extends WorkspaceProvider<{
+    readonly cwd: string;
+}, ExecutionEnv> {
+    /** Trusted host access. Raw upstream handles remain owned by the host. */
+    readonly filesystem: IFileSystem;
+    readonly createBash: (options: Omit<BashOptions, 'fs' | 'files' | 'python'>) => Bash;
+    readonly dispose: () => void;
+}
+/** Working storage: in memory (ephemeral), or the given `fs`. No publication receipts, host fallback or restart recovery. */
+export declare function createVirtualWorkspace(options: VirtualWorkspaceOptions): VirtualWorkspace;
+//# sourceMappingURL=virtual.d.ts.map

package/dist/virtual.js

@@ -0,0 +1,277 @@
+import { randomUUID } from '@hachej/boring-files/platform';
+import { posix } from 'node:path';
+import { Bash, defineCommand } from 'just-bash';
+import { FileError, ExecutionError, ok, err } from '@earendil-works/pi-durable/env';
+import { FileSystemView, VirtualFileSystem, boundedMessage } from './virtual-filesystem.js';
+import { shellCommand, snapshotReaders } from './fs-readers.js';
+export { MAX_ERROR_CHARS } from './virtual-filesystem.js';
+function fileError(error, path) {
+    if (error instanceof FileError)
+        return error;
+    const cause = error instanceof Error ? error : new Error(String(error));
+    const message = boundedMessage(cause);
+    const code = /\b(ENOENT|ENOTDIR|EISDIR|EACCES|EPERM|EEXIST|EINVAL|ENOTEMPTY)\b/.exec(message)?.[1];
+    return new FileError(code === 'ENOENT' ? 'not_found' : code === 'ENOTDIR' ? 'not_directory' : code === 'EISDIR' ? 'is_directory'
+        : code === 'EACCES' || code === 'EPERM' ? 'permission_denied' : code === 'EEXIST' || code === 'EINVAL' || code === 'ENOTEMPTY' ? 'invalid' : 'unknown', message, path, cause);
+}
+/** Working storage: in memory (ephemeral), or the given `fs`. No publication receipts, host fallback or restart recovery. */
+export function createVirtualWorkspace(options) {
+    if (typeof options.providerId !== 'string' || !options.providerId || /[\x00-\x1f]/.test(options.providerId))
+        throw new TypeError('A provider identifier is required');
+    const capture = (content) => typeof content === 'string' ? content : Uint8Array.from(content);
+    const files = Object.fromEntries(Object.entries(options.files ?? {}).map(([path, file]) => [path,
+        typeof file === 'function' ? async () => capture(await file()) : typeof file === 'string' || file instanceof Uint8Array ? capture(file)
+            : { ...file, content: capture(file.content), ...(file.mtime === undefined ? {} : { mtime: new Date(file.mtime) }) }]));
+    if (options.python === true && typeof globalThis.process?.versions?.node !== 'string') {
+        throw new TypeError('Python needs Node: just-bash runs CPython only under Node, not in a browser or its workers');
+    }
+    if (options.fs && (options.files || options.storage))
+        throw new TypeError('A virtual workspace over a file system takes no initial files or storage');
+    const filesystem = options.fs ? new FileSystemView(options.fs) : new VirtualFileSystem(files, options.storage);
+    const identity = Object.freeze({ providerId: options.providerId, instanceId: randomUUID(), incarnation: randomUUID(), viewId: randomUUID() });
+    const namespace = `virtual:${identity.instanceId}`;
+    let disposed = false;
+    const createBash = input => {
+        if (disposed)
+            throw new FileError('invalid', 'Virtual workspace is disposed');
+        const limits = options.bash?.executionLimits || input.executionLimits ? { executionLimits: { ...options.bash?.executionLimits, ...input.executionLimits } } : {};
+        // Python only when the workspace option says so, whatever a caller's shell options carry.
+        const selected = { ...options.bash, ...input, ...limits, fs: filesystem, python: options.python === true };
+        const commands = selected.customCommands ?? [];
+        const includeLinks = selected.commands === undefined || selected.commands.includes('ln');
+        const bash = new Bash({ ...selected, customCommands: includeLinks && !commands.some(command => command.name === 'ln')
+                ? [...commands, symbolicLinkCommand] : commands });
+        options.onBash?.(bash);
+        return bash;
+    };
+    return {
+        providerId: options.providerId, filesystem, createBash,
+        dispose: () => { disposed = true; },
+        acquire: async (request, context) => {
+            if (disposed)
+                throw new FileError('invalid', 'Virtual workspace is disposed');
+            if (context.abortSignal?.aborted)
+                throw new FileError('aborted', 'Workspace acquisition aborted');
+            const cwd = request.input.cwd;
+            if (typeof cwd !== 'string' || !cwd.startsWith('/') || cwd.includes('\0'))
+                throw new FileError('invalid', 'An absolute virtual cwd is required');
+            if (!(await filesystem.stat(cwd)).isDirectory)
+                throw new FileError('not_directory', 'Working directory is not a directory', cwd);
+            if (disposed || context.abortSignal?.aborted)
+                throw new FileError(disposed ? 'invalid' : 'aborted', 'Workspace acquisition is no longer available');
+            let released = false;
+            const environment = nativeEnvironment(filesystem, namespace, cwd, () => disposed || released, async () => { released = true; }, createBash);
+            return { identity, environment, ownership: 'borrowed', release: environment.cleanup };
+        },
+    };
+}
+// Stock ln -f removes the destination before calling fs.link, which this backing cannot support.
+const symbolicLinkCommand = defineCommand('ln', async (input, context) => {
+    // Stock ln lacks -T/--no-target-directory. Strip it here and refuse a directory destination as native ln does.
+    const args = [];
+    let symbolic = false, plain = false, flags = true;
+    for (const arg of input) {
+        if (flags && (arg === '--' || !arg.startsWith('-')))
+            flags = false;
+        if (flags && arg === '--no-target-directory') {
+            plain = true;
+            continue;
+        }
+        if (flags && arg.includes('T') && /^-[sfvnT]+$/.test(arg)) {
+            plain = true;
+            if (arg.replaceAll('T', '') === '-')
+                continue;
+            args.push(arg.replaceAll('T', ''));
+            if (/^-[sfvn]*s/.test(arg))
+                symbolic = true;
+            continue;
+        }
+        if (flags && (arg === '--symbolic' || /^-[sfvn]*s[sfvn]*$/.test(arg)))
+            symbolic = true;
+        args.push(arg);
+    }
+    if (!symbolic && !(args.length === 1 && args[0] === '--help')) {
+        return { stdout: '', stderr: 'ln: ENOTSUP: hard links are not supported by this backing\n', exitCode: 1 };
+    }
+    if (!context.origCommand)
+        return { stdout: '', stderr: 'ln: stock command is unavailable\n', exitCode: 126 };
+    const destination = args.at(-1);
+    if (plain && destination && !destination.startsWith('-') && await context.fs.stat(context.fs.resolvePath(context.cwd, destination)).then(stat => stat.isDirectory, () => false)) {
+        return { stdout: '', stderr: `ln: cannot overwrite directory '${destination}'\n`, exitCode: 1 };
+    }
+    return context.origCommand(args);
+});
+function nativeEnvironment(fs, id, cwd, closed, release, createBash) {
+    const failure = (context, path) => closed() ? new FileError('invalid', 'Workspace lease is closed', path)
+        : context.abortSignal?.aborted ? new FileError('aborted', 'Operation aborted', path) : undefined;
+    const absolute = (path) => {
+        if (typeof path !== 'string' || path.includes('\0') || typeof environment.cwd !== 'string' || !environment.cwd.startsWith('/'))
+            throw new FileError('invalid', 'Invalid virtual path', path);
+        return posix.resolve(environment.cwd, path);
+    };
+    async function run(path, context, operation) {
+        try {
+            const before = failure(context, path);
+            if (before)
+                return err(before);
+            const value = await operation(absolute(path));
+            const after = failure(context, path);
+            return after ? err(after) : ok(value);
+        }
+        catch (error) {
+            return err(fileError(error, path));
+        }
+    }
+    const info = async (path) => {
+        const stat = await fs.lstat(path);
+        return { path, name: posix.basename(path), kind: stat.isSymbolicLink ? 'symlink' : stat.isDirectory ? 'directory' : 'file', size: stat.size, mtimeMs: stat.mtime.getTime() };
+    };
+    async function temporary(prefix, suffix, directory) {
+        if (prefix.includes('/') || suffix.includes('/') || prefix.includes('\0') || suffix.includes('\0'))
+            throw new FileError('invalid', 'Temporary names must be basenames');
+        await fs.mkdir('/tmp', { recursive: true });
+        const path = `/tmp/${prefix}${randomUUID()}${suffix}`;
+        await fs.createExclusive(path, { mode: directory ? 0o700 : 0o600, directory });
+        return path;
+    }
+    // Readers and the watcher over the memory file system's whole-file reads (see fs-readers.ts).
+    const readers = snapshotReaders({ readBinaryFile: (path, context) => environment.readBinaryFile(path, context), fileInfo: (path, context) => environment.fileInfo(path, context), listDir: (path, context) => environment.listDir(path, context) });
+    const environment = {
+        id, cwd: posix.normalize(cwd), ...readers,
+        absolutePath: (path, context) => run(path, context, path => path),
+        joinPath: (parts, context) => run('.', context, () => posix.join(...parts)),
+        readTextFile: (path, context) => run(path, context, path => fs.readFile(path)),
+        readBinaryFile: (path, context) => run(path, context, async (path) => Uint8Array.from(await fs.readFileBuffer(path))),
+        writeFile: (path, content, context) => run(path, context, path => fs.writeFile(path, typeof content === 'string' ? content : Uint8Array.from(content))),
+        appendFile: (path, content, context) => run(path, context, path => fs.appendFile(path, typeof content === 'string' ? content : Uint8Array.from(content))),
+        truncateFile: (path, size, context) => run(path, context, path => {
+            if (!Number.isSafeInteger(size) || size < 0)
+                throw new FileError('invalid', 'File size must be a non-negative safe integer', path);
+            throw new FileError('not_supported', 'The selected backing has no atomic truncate operation', path);
+        }),
+        flushFile: (path, context) => run(path, context, () => { throw new FileError('not_supported', 'Memory storage cannot flush to durable backing', path); }),
+        // Qualified for one regular file onto a file or a missing path only; anything else keeps refusing before effects.
+        renameFile: (source, destination, context) => run(source, context, async (from) => {
+            const to = absolute(destination);
+            try {
+                await fs.replaceFile(from, to);
+            }
+            catch (error) {
+                if (error instanceof Error && /\b(ENOTSUP|EISDIR)\b/.test(error.message))
+                    throw new FileError('not_supported', 'The selected backing renames a regular file onto a file or a missing path only', from);
+                throw error;
+            }
+        }),
+        fileInfo: (path, context) => run(path, context, info),
+        listDir: (path, context) => run(path, context, async (path) => Promise.all((await fs.readdir(path)).map(name => info(posix.join(path, name))))),
+        canonicalPath: (path, context) => run(path, context, path => fs.realpath(path)),
+        exists: (path, context) => run(path, context, async (path) => {
+            try {
+                await fs.lstat(path);
+                return true;
+            }
+            catch (error) {
+                if (fileError(error, path).code === 'not_found')
+                    return false;
+                throw error;
+            }
+        }),
+        createDir: (path, options, context) => run(path, context, path => fs.mkdir(path, { ...options, recursive: options?.recursive ?? true })),
+        remove: (path, options, context) => run(path, context, path => fs.rm(path, options)),
+        createTempDir: (prefix, context) => run('.', context, () => temporary(prefix ?? 'boring-', '', true)),
+        createTempFile: (options, context) => run('.', context, () => temporary(options?.prefix ?? 'boring-', options?.suffix ?? '', false)),
+        openTextLineReader: (path, context) => run(path, context, async (path) => {
+            const text = await fs.readFile(path);
+            let offset = 0, readerClosed = false;
+            const reader = {
+                readLine: async (context) => {
+                    const invalid = failure(context, path);
+                    if (invalid)
+                        return err(invalid);
+                    if (readerClosed)
+                        return err(new FileError('invalid', 'Text line reader is closed', path));
+                    if (offset === text.length)
+                        return ok(undefined);
+                    const newline = text.indexOf('\n', offset);
+                    const line = { text: text.slice(offset, newline === -1 ? undefined : newline), terminated: newline !== -1 };
+                    offset = newline === -1 ? text.length : newline + 1;
+                    return ok(line);
+                },
+                close: async () => { readerClosed = true; },
+            };
+            return reader;
+        }),
+        readTextLines: async (path, options, context) => {
+            if (options?.maxLines !== undefined && options.maxLines <= 0)
+                return ok([]);
+            const opened = await environment.openTextLineReader(path, context);
+            if (!opened.ok)
+                return opened;
+            const lines = [];
+            try {
+                while (options?.maxLines === undefined || lines.length < options.maxLines) {
+                    const line = await opened.value.readLine(context);
+                    if (!line.ok)
+                        return line;
+                    if (line.value === undefined)
+                        break;
+                    lines.push(line.value.text);
+                }
+                return ok(lines);
+            }
+            finally {
+                await opened.value.close(context);
+            }
+        },
+        exec: async (command, options, context) => {
+            if (closed())
+                return err(new ExecutionError('shell_unavailable', 'Workspace lease is closed'));
+            if (context.abortSignal?.aborted)
+                return err(new ExecutionError('aborted', 'Command aborted'));
+            // just-bash buffers output: `onOutput` receives it once when the command ends, never as a live stream, and
+            // nothing is spilled to a file. This is what lets Pi's stock bash tool run here. `timeout` is in seconds.
+            const timer = new AbortController(), signals = [timer.signal, ...(context.abortSignal ? [context.abortSignal] : [])];
+            const started = Date.now();
+            const timeout = options?.timeout === undefined ? undefined : setTimeout(() => timer.abort(), options.timeout * 1000);
+            try {
+                const cwd = absolute(options?.cwd ?? '.');
+                try {
+                    if (!(await fs.stat(cwd)).isDirectory)
+                        throw new Error('not a directory');
+                }
+                catch (cause) {
+                    return err(new ExecutionError('spawn_error', `Working directory does not exist: ${cwd}\nCannot execute bash commands.`, cause instanceof Error ? cause : undefined));
+                }
+                const result = await createBash({ cwd, ...(options?.timeout === undefined ? {} : { executionLimits: { maxExecutionTimeMs: options.timeout * 1000 } }) }).exec(shellCommand(command), {
+                    ...(options?.env === undefined ? {} : { env: options.env }), replaceEnv: options?.inheritEnv === false,
+                    signal: AbortSignal.any(signals),
+                });
+                if (context.abortSignal?.aborted)
+                    return err(new ExecutionError('aborted', 'Command aborted; prior effects may remain'));
+                // A synchronous script never yields to the timer above; just-bash's own wall-clock limit stops it instead.
+                if (timer.signal.aborted || options?.timeout !== undefined && result.exitCode !== 0 && Date.now() - started >= options.timeout * 1000)
+                    return err(new ExecutionError('timeout', 'Command timed out; prior effects may remain'));
+                if (options?.onOutput) {
+                    try {
+                        if (result.stdout)
+                            options.onOutput(result.stdout, context, { stream: 'stdout' });
+                        if (result.stderr)
+                            options.onOutput(result.stderr, context, { stream: 'stderr' });
+                    }
+                    catch (error) {
+                        return err(new ExecutionError('callback_error', boundedMessage(error), error instanceof Error ? error : undefined));
+                    }
+                }
+                return ok({ exitCode: result.exitCode });
+            }
+            catch (error) {
+                return err(new ExecutionError('unknown', boundedMessage(error), error instanceof Error ? error : undefined));
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        },
+        cleanup: release,
+    };
+    return environment;
+}

package/package.json

@@ -1,6 +1,96 @@
 {
   "name": "@hachej/boring-execution",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "description": "Native Pi working-environment types and independently composable workspace leases.",
+  "sideEffects": false,
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./native": {
+      "types": "./dist/native.d.ts",
+      "import": "./dist/native.js"
+    },
+    "./contracts": {
+      "types": "./dist/contracts.d.ts",
+      "import": "./dist/contracts.js"
+    },
+    "./virtual": {
+      "types": "./dist/virtual.d.ts",
+      "import": "./dist/virtual.js"
+    },
+    "./virtual-git": {
+      "types": "./dist/virtual-git.d.ts",
+      "import": "./dist/virtual-git.js"
+    },
+    "./remote-shell": {
+      "types": "./dist/remote-shell.d.ts",
+      "import": "./dist/remote-shell.js"
+    },
+    "./remote-files": {
+      "types": "./dist/remote-files.d.ts",
+      "import": "./dist/remote-files.js"
+    },
+    "./virtual-sqlite": {
+      "types": "./dist/virtual-sqlite.d.ts",
+      "import": "./dist/virtual-sqlite.js"
+    },
+    "./aws-code-interpreter": {
+      "types": "./dist/aws-code-interpreter.d.ts",
+      "import": "./dist/aws-code-interpreter.js"
+    }
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-durable": "1.1.0",
+    "@earendil-works/chord": "1.1.0",
+    "just-bash": "3.6.0",
+    "isomorphic-git": "1.42.6",
+    "@hachej/boring-files": "0.2.1",
+    "zod": "4.6.5",
+    "@aws-sdk/client-bedrock-agentcore": "3.1146.0"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "peerDependenciesMeta": {
+    "just-bash": {
+      "optional": true
+    },
+    "isomorphic-git": {
+      "optional": true
+    },
+    "@hachej/boring-files": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    },
+    "@aws-sdk/client-bedrock-agentcore": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hachej/boring-ui.git",
+    "directory": "packages/execution"
+  },
+  "homepage": "https://github.com/hachej/boring-ui#readme",
+  "bugs": {
+    "url": "https://github.com/hachej/boring-ui/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}