@hachej/boring-execution 0.0.0-stage → 0.2.1

package/dist/remote-files-protocol.d.ts

@@ -0,0 +1,342 @@
+import { z } from 'zod';
+import { FileError } from '@earendil-works/pi-durable/env';
+import type { FileInfo, FileSystem, Result, WatchChange, WatchTarget } from '@earendil-works/pi-durable/env';
+import type { Context } from '@earendil-works/chord';
+export { identity, sameIdentity, positiveLimit, nativeVersion } from './remote-shell-protocol.js';
+export declare const schema = "boring.remote-files";
+export declare const version = 3;
+export declare const streamType = "application/x-ndjson";
+/**
+ * Native methods sent over the wire unchanged. Pi's stateful readers (`openBinaryReader`, `openDirReader`) hold an open handle; a
+ * stateless request cannot, so they travel as the request-bound methods of `PositionalCall`, and `watch` as one streamed request.
+ */
+export type FileMethod = Exclude<keyof FileSystem, 'id' | 'cwd' | 'cleanup' | 'openBinaryReader' | 'openDirReader' | 'watch'>;
+type Arguments<Method> = Method extends (...args: [...infer Input, Context]) => unknown ? Input : never;
+type NativeCall = {
+    [Method in FileMethod]: {
+        readonly method: Method;
+        readonly args: Arguments<FileSystem[Method]>;
+    };
+}[FileMethod];
+/** What a file looked like when the client opened it. A positional request fails when the file no longer matches (`FileInfo` has no inode). */
+export interface ExpectedFile {
+    readonly size: number;
+    readonly mtimeMs: number;
+}
+export interface ReaderOptions {
+    readonly noFollow?: boolean;
+}
+export interface DirPage {
+    readonly entries: FileInfo[];
+    readonly done: boolean;
+    readonly mtimeMs: number;
+}
+/** Each call opens the native reader, answers one bounded request and closes it, so no reader outlives a request. */
+export type PositionalCall = {
+    readonly method: 'binaryInfo';
+    readonly args: readonly [path: string, options: ReaderOptions | undefined];
+} | {
+    readonly method: 'readRange';
+    readonly args: readonly [path: string, options: ReaderOptions | undefined, offset: number, length: number, expected: ExpectedFile | undefined];
+} | {
+    readonly method: 'scanLines';
+    readonly args: readonly [path: string, options: ReaderOptions | undefined, lines: {
+        readonly startLine: number;
+        readonly endLine?: number;
+    }, expected: ExpectedFile | undefined];
+}
+/** `maxEntries` 0 only opens the directory (native open errors, `mtimeMs`); `offset` counts entries the native reader already returned. */
+ | {
+    readonly method: 'readDirPage';
+    readonly args: readonly [path: string, offset: number, maxEntries: number, expectedMtimeMs: number | undefined];
+};
+export type WatchCall = {
+    readonly method: 'watch';
+    readonly args: readonly [targets: readonly WatchTarget[]];
+};
+export type RemoteFileSystemCall = NativeCall | PositionalCall | WatchCall;
+/** Largest `readRange` the response limit can carry as canonical base64 inside its envelope. */
+export declare function maxRangeBytes(maxResponseBytes: number): number;
+export declare const maxDirPageEntries = 1000, maxWatchTargets = 64, maxWatchExcludeNames = 256;
+/** Bytes travel as canonical base64 text; JSON number arrays multiplied the size by three to four. */
+export declare function encodeBytes(value: Uint8Array): string;
+export declare function decodeBytes(value: string): Uint8Array;
+export declare const bytes: z.ZodPipe<z.ZodString, z.ZodTransform<Uint8Array<ArrayBufferLike>, string>>;
+declare const requestSchema: z.ZodObject<{
+    cwd: z.ZodString;
+    call: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        method: z.ZodLiteral<"absolutePath">;
+        args: z.ZodTuple<[z.ZodString], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"readTextFile">;
+        args: z.ZodTuple<[z.ZodString], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"openTextLineReader">;
+        args: z.ZodTuple<[z.ZodString], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"readBinaryFile">;
+        args: z.ZodTuple<[z.ZodString], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"flushFile">;
+        args: z.ZodTuple<[z.ZodString], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"fileInfo">;
+        args: z.ZodTuple<[z.ZodString], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"listDir">;
+        args: z.ZodTuple<[z.ZodString], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"canonicalPath">;
+        args: z.ZodTuple<[z.ZodString], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"exists">;
+        args: z.ZodTuple<[z.ZodString], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"joinPath">;
+        args: z.ZodTuple<[z.ZodArray<z.ZodString>], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"readTextLines">;
+        args: z.ZodTuple<[z.ZodString, z.ZodPipe<z.ZodNullable<z.ZodObject<{
+            maxLines: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>, z.ZodTransform<{
+            maxLines?: never;
+        } | {
+            maxLines: number;
+        } | undefined, {
+            maxLines?: number | undefined;
+        } | null>>], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"writeFile">;
+        args: z.ZodTuple<[z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodObject<{
+            bytes: z.ZodPipe<z.ZodString, z.ZodTransform<Uint8Array<ArrayBufferLike>, string>>;
+        }, z.core.$strict>, z.ZodTransform<Uint8Array<ArrayBufferLike>, {
+            bytes: Uint8Array<ArrayBufferLike>;
+        }>>]>], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"appendFile">;
+        args: z.ZodTuple<[z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodPipe<z.ZodObject<{
+            bytes: z.ZodPipe<z.ZodString, z.ZodTransform<Uint8Array<ArrayBufferLike>, string>>;
+        }, z.core.$strict>, z.ZodTransform<Uint8Array<ArrayBufferLike>, {
+            bytes: Uint8Array<ArrayBufferLike>;
+        }>>]>], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"truncateFile">;
+        args: z.ZodTuple<[z.ZodString, z.ZodNumber], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"renameFile">;
+        args: z.ZodTuple<[z.ZodString, z.ZodString], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"createDir">;
+        args: z.ZodTuple<[z.ZodString, z.ZodPipe<z.ZodNullable<z.ZodObject<{
+            recursive: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>, z.ZodTransform<{
+            recursive?: never;
+        } | {
+            recursive: boolean;
+        } | undefined, {
+            recursive?: boolean | undefined;
+        } | null>>], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"remove">;
+        args: z.ZodTuple<[z.ZodString, z.ZodPipe<z.ZodNullable<z.ZodObject<{
+            recursive: z.ZodOptional<z.ZodBoolean>;
+            force: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>, z.ZodTransform<{
+            force?: boolean;
+            recursive?: boolean;
+        } | undefined, {
+            recursive?: boolean | undefined;
+            force?: boolean | undefined;
+        } | null>>], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"createTempDir">;
+        args: z.ZodTuple<[z.ZodPipe<z.ZodNullable<z.ZodString>, z.ZodTransform<string | undefined, string | null>>], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"createTempFile">;
+        args: z.ZodTuple<[z.ZodPipe<z.ZodNullable<z.ZodObject<{
+            prefix: z.ZodOptional<z.ZodString>;
+            suffix: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>, z.ZodTransform<{
+            suffix?: string;
+            prefix?: string;
+        } | undefined, {
+            prefix?: string | undefined;
+            suffix?: string | undefined;
+        } | null>>], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"binaryInfo">;
+        args: z.ZodTuple<[z.ZodString, z.ZodPipe<z.ZodNullable<z.ZodObject<{
+            noFollow: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>, z.ZodTransform<{
+            noFollow?: never;
+        } | {
+            noFollow: boolean;
+        } | undefined, {
+            noFollow?: boolean | undefined;
+        } | null>>], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"readRange">;
+        args: z.ZodTuple<[z.ZodString, z.ZodPipe<z.ZodNullable<z.ZodObject<{
+            noFollow: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>, z.ZodTransform<{
+            noFollow?: never;
+        } | {
+            noFollow: boolean;
+        } | undefined, {
+            noFollow?: boolean | undefined;
+        } | null>>, z.ZodNumber, z.ZodNumber, z.ZodPipe<z.ZodNullable<z.ZodObject<{
+            size: z.ZodNumber;
+            mtimeMs: z.ZodNumber;
+        }, z.core.$strict>>, z.ZodTransform<{
+            size: number;
+            mtimeMs: number;
+        } | undefined, {
+            size: number;
+            mtimeMs: number;
+        } | null>>], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"scanLines">;
+        args: z.ZodTuple<[z.ZodString, z.ZodPipe<z.ZodNullable<z.ZodObject<{
+            noFollow: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>, z.ZodTransform<{
+            noFollow?: never;
+        } | {
+            noFollow: boolean;
+        } | undefined, {
+            noFollow?: boolean | undefined;
+        } | null>>, z.ZodPipe<z.ZodObject<{
+            startLine: z.ZodNumber;
+            endLine: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>, z.ZodTransform<{
+            startLine: number;
+            endLine?: never;
+        } | {
+            startLine: number;
+            endLine: number;
+        }, {
+            startLine: number;
+            endLine?: number | undefined;
+        }>>, z.ZodPipe<z.ZodNullable<z.ZodObject<{
+            size: z.ZodNumber;
+            mtimeMs: z.ZodNumber;
+        }, z.core.$strict>>, z.ZodTransform<{
+            size: number;
+            mtimeMs: number;
+        } | undefined, {
+            size: number;
+            mtimeMs: number;
+        } | null>>], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"readDirPage">;
+        args: z.ZodTuple<[z.ZodString, z.ZodNumber, z.ZodNumber, z.ZodPipe<z.ZodNullable<z.ZodNumber>, z.ZodTransform<number | undefined, number | null>>], null>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"watch">;
+        args: z.ZodTuple<[z.ZodArray<z.ZodPipe<z.ZodObject<{
+            path: z.ZodString;
+            recursive: z.ZodOptional<z.ZodBoolean>;
+            exclude: z.ZodOptional<z.ZodObject<{
+                hidden: z.ZodOptional<z.ZodBoolean>;
+                names: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodTransform<WatchTarget, {
+            path: string;
+            recursive?: boolean | undefined;
+            exclude?: {
+                hidden?: boolean | undefined;
+                names?: string[] | undefined;
+            } | undefined;
+        }>>>], null>;
+    }, z.core.$strict>], "method">;
+    schema: z.ZodLiteral<"boring.remote-files">;
+    version: z.ZodLiteral<3>;
+    nativeVersion: z.ZodLiteral<"pi-durable@1.1.0">;
+    requestId: z.ZodString;
+    identity: z.ZodPipe<z.ZodUnknown, z.ZodTransform<import("./contracts.js").WorkspaceIdentity, unknown>>;
+    filesystemId: z.ZodString;
+}, z.core.$strict>;
+export declare function requestInput(value: unknown): Omit<z.infer<typeof requestSchema>, 'call'> & {
+    readonly call: RemoteFileSystemCall;
+};
+export declare const envelope: z.ZodObject<{
+    result: z.ZodUnknown;
+    schema: z.ZodLiteral<"boring.remote-files">;
+    version: z.ZodLiteral<3>;
+    nativeVersion: z.ZodLiteral<"pi-durable@1.1.0">;
+    requestId: z.ZodString;
+    identity: z.ZodPipe<z.ZodUnknown, z.ZodTransform<import("./contracts.js").WorkspaceIdentity, unknown>>;
+    filesystemId: z.ZodString;
+}, z.core.$strict>;
+export declare const fileInfo: z.ZodObject<{
+    name: z.ZodString;
+    path: z.ZodString;
+    kind: z.ZodEnum<{
+        file: "file";
+        directory: "directory";
+        symlink: "symlink";
+    }>;
+    size: z.ZodNumber;
+    mtimeMs: z.ZodNumber;
+}, z.core.$strict>;
+export declare const lineScan: z.ZodObject<{
+    newlines: z.ZodNumber;
+    start: z.ZodNumber;
+    end: z.ZodNumber;
+    firstLineEnd: z.ZodNumber;
+    lastLineStart: z.ZodNumber;
+    selectedBytes: z.ZodNumber;
+    firstLineBytes: z.ZodNumber;
+}, z.core.$strict>;
+export declare const dirPage: z.ZodObject<{
+    entries: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        path: z.ZodString;
+        kind: z.ZodEnum<{
+            file: "file";
+            directory: "directory";
+            symlink: "symlink";
+        }>;
+        size: z.ZodNumber;
+        mtimeMs: z.ZodNumber;
+    }, z.core.$strict>>;
+    done: z.ZodBoolean;
+    mtimeMs: z.ZodNumber;
+}, z.core.$strict>;
+export declare const line: z.ZodObject<{
+    text: z.ZodString;
+    terminated: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const nothing: z.ZodPipe<z.ZodNull, z.ZodTransform<undefined, null>>;
+export declare function result<Value>(value: unknown, output: z.ZodType<Value>): Result<Value, FileError>;
+export declare function wireResult(value: Result<unknown, FileError>): unknown;
+export declare function parseWatchChange(value: unknown): WatchChange;
+export declare function wireWatchChange(change: WatchChange): unknown;
+export declare const streamFrame: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    sequence: z.ZodLiteral<0>;
+    type: z.ZodLiteral<"opened">;
+    mode: z.ZodOptional<z.ZodEnum<{
+        native: "native";
+        polling: "polling";
+    }>>;
+    schema: z.ZodLiteral<"boring.remote-files">;
+    version: z.ZodLiteral<3>;
+    nativeVersion: z.ZodLiteral<"pi-durable@1.1.0">;
+    requestId: z.ZodString;
+    identity: z.ZodPipe<z.ZodUnknown, z.ZodTransform<import("./contracts.js").WorkspaceIdentity, unknown>>;
+    filesystemId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    type: z.ZodLiteral<"change">;
+    change: z.ZodUnknown;
+}, z.core.$strict>, z.ZodObject<{
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    type: z.ZodLiteral<"line">;
+    result: z.ZodUnknown;
+}, z.core.$strict>, z.ZodObject<{
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    type: z.ZodLiteral<"end">;
+}, z.core.$strict>], "type">;
+export declare function wireCall(call: RemoteFileSystemCall): unknown;
+//# sourceMappingURL=remote-files-protocol.d.ts.map

package/dist/remote-files-protocol.js

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+import { FileError, ok, err } from '@earendil-works/pi-durable/env';
+import { identity, nativeVersion } from './remote-shell-protocol.js';
+export { identity, sameIdentity, positiveLimit, nativeVersion } from './remote-shell-protocol.js';
+export const schema = 'boring.remote-files';
+export const version = 3;
+export const streamType = 'application/x-ndjson';
+/** Largest `readRange` the response limit can carry as canonical base64 inside its envelope. */
+export function maxRangeBytes(maxResponseBytes) { return Math.max(1, Math.floor((maxResponseBytes - 2048) / 4) * 3); }
+export const maxDirPageEntries = 1000, maxWatchTargets = 64, maxWatchExcludeNames = 256;
+const text = z.string(), number = z.number().finite();
+/** Bytes travel as canonical base64 text; JSON number arrays multiplied the size by three to four. */
+export function encodeBytes(value) {
+    let text = '';
+    for (let index = 0; index < value.length; index += 0x8000)
+        text += String.fromCharCode(...value.subarray(index, index + 0x8000));
+    return btoa(text);
+}
+export function decodeBytes(value) {
+    let text;
+    try {
+        text = atob(value);
+    }
+    catch {
+        throw new TypeError('Invalid resource bytes');
+    }
+    const result = new Uint8Array(text.length);
+    for (let index = 0; index < text.length; index++)
+        result[index] = text.charCodeAt(index);
+    if (encodeBytes(result) !== value)
+        throw new TypeError('Invalid resource bytes');
+    return result;
+}
+export const bytes = z.string().transform(decodeBytes);
+const content = z.union([text, z.strictObject({ bytes }).transform(value => value.bytes)]);
+const optionalText = text.nullable().transform(value => value ?? undefined);
+const recursive = z.strictObject({ recursive: z.boolean().optional() }).nullable().transform(value => value === null ? undefined : value.recursive === undefined ? {} : { recursive: value.recursive });
+const removeOptions = z.strictObject({ recursive: z.boolean().optional(), force: z.boolean().optional() }).nullable().transform(value => value === null ? undefined : ({ ...(value.recursive === undefined ? {} : { recursive: value.recursive }), ...(value.force === undefined ? {} : { force: value.force }) }));
+const lineOptions = z.strictObject({ maxLines: number.optional() }).nullable().transform(value => value === null ? undefined : value.maxLines === undefined ? {} : { maxLines: value.maxLines });
+const tempOptions = z.strictObject({ prefix: text.optional(), suffix: text.optional() }).nullable().transform(value => value === null ? undefined : ({ ...(value.prefix === undefined ? {} : { prefix: value.prefix }), ...(value.suffix === undefined ? {} : { suffix: value.suffix }) }));
+const int = z.number().int().nonnegative();
+const readerOptions = z.strictObject({ noFollow: z.boolean().optional() }).nullable().transform(value => value === null ? undefined : value.noFollow === undefined ? {} : { noFollow: value.noFollow });
+const expectedFile = z.strictObject({ size: number.nonnegative(), mtimeMs: number }).nullable().transform(value => value ?? undefined);
+const lineRange = z.strictObject({ startLine: int, endLine: int.optional() }).transform(value => value.endLine === undefined ? { startLine: value.startLine } : { startLine: value.startLine, endLine: value.endLine });
+const watchTarget = z.strictObject({
+    path: text, recursive: z.boolean().optional(),
+    exclude: z.strictObject({ hidden: z.boolean().optional(), names: z.array(text).max(maxWatchExcludeNames).optional() }).optional(),
+}).transform((value) => ({
+    path: value.path, ...(value.recursive === undefined ? {} : { recursive: value.recursive }),
+    ...(value.exclude === undefined ? {} : { exclude: { ...(value.exclude.hidden === undefined ? {} : { hidden: value.exclude.hidden }), ...(value.exclude.names === undefined ? {} : { names: value.exclude.names }) } }),
+}));
+const pathCall = (method) => z.strictObject({ method: z.literal(method), args: z.tuple([text]) });
+const callSchema = z.discriminatedUnion('method', [
+    pathCall('absolutePath'), pathCall('readTextFile'), pathCall('openTextLineReader'), pathCall('readBinaryFile'),
+    pathCall('flushFile'), pathCall('fileInfo'), pathCall('listDir'), pathCall('canonicalPath'), pathCall('exists'),
+    z.strictObject({ method: z.literal('joinPath'), args: z.tuple([z.array(text)]) }),
+    z.strictObject({ method: z.literal('readTextLines'), args: z.tuple([text, lineOptions]) }),
+    z.strictObject({ method: z.literal('writeFile'), args: z.tuple([text, content]) }),
+    z.strictObject({ method: z.literal('appendFile'), args: z.tuple([text, content]) }),
+    z.strictObject({ method: z.literal('truncateFile'), args: z.tuple([text, number]) }),
+    z.strictObject({ method: z.literal('renameFile'), args: z.tuple([text, text]) }),
+    z.strictObject({ method: z.literal('createDir'), args: z.tuple([text, recursive]) }),
+    z.strictObject({ method: z.literal('remove'), args: z.tuple([text, removeOptions]) }),
+    z.strictObject({ method: z.literal('createTempDir'), args: z.tuple([optionalText]) }),
+    z.strictObject({ method: z.literal('createTempFile'), args: z.tuple([tempOptions]) }),
+    z.strictObject({ method: z.literal('binaryInfo'), args: z.tuple([text, readerOptions]) }),
+    z.strictObject({ method: z.literal('readRange'), args: z.tuple([text, readerOptions, int, int, expectedFile]) }),
+    z.strictObject({ method: z.literal('scanLines'), args: z.tuple([text, readerOptions, lineRange, expectedFile]) }),
+    z.strictObject({ method: z.literal('readDirPage'), args: z.tuple([text, int, int.max(maxDirPageEntries), z.number().finite().nullable().transform(value => value ?? undefined)]) }),
+    z.strictObject({ method: z.literal('watch'), args: z.tuple([z.array(watchTarget).min(1).max(maxWatchTargets)]) }),
+]);
+const binding = { schema: z.literal(schema), version: z.literal(version), nativeVersion: z.literal(nativeVersion),
+    requestId: text.min(1).max(128), identity: z.unknown().transform(identity), filesystemId: text.min(1) };
+const requestSchema = z.strictObject({ ...binding, cwd: text, call: callSchema });
+export function requestInput(value) { return requestSchema.parse(value); }
+export const envelope = z.strictObject({ ...binding, result: z.unknown() });
+export const fileInfo = z.strictObject({ name: text, path: text, kind: z.enum(['file', 'directory', 'symlink']), size: number.nonnegative(), mtimeMs: number });
+export const lineScan = z.strictObject({ newlines: int, start: int, end: int, firstLineEnd: int, lastLineStart: int, selectedBytes: int, firstLineBytes: int });
+export const dirPage = z.strictObject({ entries: z.array(fileInfo), done: z.boolean(), mtimeMs: number });
+export const line = z.strictObject({ text, terminated: z.boolean() });
+export const nothing = z.null().transform(() => undefined);
+const fileError = z.strictObject({ code: z.enum(['aborted', 'not_found', 'permission_denied', 'not_directory', 'is_directory', 'invalid', 'not_supported', 'unknown']), message: text, path: text.optional() });
+export function result(value, output) {
+    const parsed = z.discriminatedUnion('ok', [z.strictObject({ ok: z.literal(true), value: output }), z.strictObject({ ok: z.literal(false), error: fileError })]).parse(value);
+    return parsed.ok ? ok(parsed.value) : err(new FileError(parsed.error.code, parsed.error.message, parsed.error.path));
+}
+export function wireResult(value) {
+    if (value.ok)
+        return { ok: true, value: value.value instanceof Uint8Array ? encodeBytes(value.value) : value.value ?? null };
+    return { ok: false, error: { code: value.error.code, message: value.error.message, ...(value.error.path === undefined ? {} : { path: value.error.path }) } };
+}
+const watchChange = z.union([
+    z.strictObject({ paths: z.array(text) }),
+    z.strictObject({ overflow: z.literal(true) }),
+    z.strictObject({ error: fileError }).transform(value => ({ error: new FileError(value.error.code, value.error.message, value.error.path) })),
+]);
+export function parseWatchChange(value) { return watchChange.parse(value); }
+export function wireWatchChange(change) {
+    if ('error' in change)
+        return { error: { code: change.error.code, message: change.error.message, ...(change.error.path === undefined ? {} : { path: change.error.path }) } };
+    return change;
+}
+export const streamFrame = z.discriminatedUnion('type', [
+    z.strictObject({ ...binding, sequence: z.literal(0), type: z.literal('opened'), mode: z.enum(['native', 'polling']).optional() }),
+    z.strictObject({ requestId: binding.requestId, sequence: z.number().int().positive(), type: z.literal('change'), change: z.unknown() }),
+    z.strictObject({ requestId: binding.requestId, sequence: z.number().int().positive(), type: z.literal('line'), result: z.unknown() }),
+    z.strictObject({ requestId: binding.requestId, sequence: z.number().int().positive(), type: z.literal('end') }),
+]);
+export function wireCall(call) {
+    // JSON has no Infinity; an unbounded line count is the same request as no limit.
+    const unbounded = call.method === 'readTextLines' && call.args[1]?.maxLines === Infinity;
+    return { method: call.method, args: call.args.map((value, index) => unbounded && index === 1 ? {} : value instanceof Uint8Array ? { bytes: encodeBytes(value) } : value ?? null) };
+}

package/dist/remote-files-watch.d.ts

@@ -0,0 +1,29 @@
+import type { Context } from '@earendil-works/chord';
+import { FileError } from '@earendil-works/pi-durable/env';
+import type { FileSystem, FileWatcher, Result, WatchChange, WatchTarget } from '@earendil-works/pi-durable/env';
+export interface ServeWatch {
+    readonly fs: FileSystem;
+    readonly targets: readonly WatchTarget[];
+    readonly binding: object;
+    readonly requestId: string;
+    readonly context: Context;
+    readonly cleanup: Context;
+    readonly maxFrameBytes: number;
+    /** Re-check authorization and binding before each disclosure. */
+    readonly permitted: () => Promise<boolean>;
+    /** Close the watcher's lease facade; called once after the watcher has closed. */
+    readonly release: () => Promise<void>;
+    readonly onCleanupError?: ((error: unknown) => void) | undefined;
+    readonly stop: () => void;
+}
+/** Start the native watcher. A failure to establish coverage is a normal result; otherwise a stream response that owns the watcher. */
+export declare function serveWatch(o: ServeWatch): Promise<Result<Response, FileError>>;
+/** Client side: consume an `opened` + `change` stream into Pi's `FileWatcher`. `deliver` is never called after `close` resolves. */
+export declare function watcherFromFrames(options: {
+    readonly mode: 'native' | 'polling';
+    readonly next: () => Promise<unknown>;
+    readonly requestId: string;
+    readonly onChange: (change: WatchChange) => void;
+    readonly dispose: () => Promise<void>;
+}): FileWatcher;
+//# sourceMappingURL=remote-files-watch.d.ts.map

package/dist/remote-files-watch.js

@@ -0,0 +1,154 @@
+import { FileError, ok } from '@earendil-works/pi-durable/env';
+import { parseWatchChange, streamFrame, streamType, wireWatchChange } from './remote-files-protocol.js';
+const maxQueuedChanges = 256;
+const encode = (value) => new TextEncoder().encode(JSON.stringify(value) + '\n');
+/** Start the native watcher. A failure to establish coverage is a normal result; otherwise a stream response that owns the watcher. */
+export async function serveWatch(o) {
+    const queue = [];
+    let wake, ended = false, finished = false;
+    // A native `error` ends the watcher and must reach the client whatever happened to the queued events before it.
+    let terminal;
+    const signal = o.context.abortSignal;
+    const push = (change) => {
+        if (ended || terminal !== undefined)
+            return;
+        if ('error' in change)
+            terminal = change;
+        else if (queue.length >= maxQueuedChanges) {
+            queue.length = 0;
+            queue.push({ overflow: true });
+        }
+        else
+            queue.push(change);
+        wake?.();
+    };
+    const opened = await o.fs.watch(o.targets, push, o.context);
+    if (!opened.ok)
+        return opened;
+    const watcher = opened.value;
+    let closing;
+    const close = () => closing ??= (async () => {
+        ended = true;
+        wake?.();
+        try {
+            await watcher.close(o.cleanup);
+        }
+        finally {
+            await o.release();
+        }
+    })();
+    let controller;
+    let sequence = 1;
+    const interrupt = () => {
+        if (finished)
+            return;
+        finished = true;
+        signal?.removeEventListener('abort', interrupt);
+        controller.error(new Error('Remote file watch interrupted'));
+        void close().catch(error => o.onCleanupError?.(error));
+    };
+    const frameFor = (change) => {
+        const frame = (value) => encode({ requestId: o.requestId, sequence, type: 'change', change: wireWatchChange(value) });
+        const bytes = frame(change);
+        if (bytes.length <= o.maxFrameBytes)
+            return bytes;
+        if ('error' in change) {
+            // Never turn a terminal error into an event: bound its text, then fall back to a fixed message.
+            const bounded = (limit) => ({ error: new FileError(change.error.code, change.error.message.slice(0, limit), change.error.path === undefined ? undefined : change.error.path.slice(0, limit)) });
+            for (const limit of [512, 64]) {
+                const shorter = frame(bounded(limit));
+                if (shorter.length <= o.maxFrameBytes)
+                    return shorter;
+            }
+            return frame({ error: new FileError('unknown', 'Watcher failed') });
+        }
+        return frame({ overflow: true });
+    };
+    const body = new ReadableStream({
+        start(value) {
+            controller = value;
+            controller.enqueue(encode({ ...o.binding, type: 'opened', sequence: 0, mode: watcher.mode }));
+            signal?.addEventListener('abort', interrupt, { once: true });
+            if (signal?.aborted)
+                interrupt();
+        },
+        async pull() {
+            try {
+                while (!finished && queue.length === 0 && terminal === undefined && !ended)
+                    await new Promise(resolve => { wake = resolve; });
+                wake = undefined;
+                if (finished)
+                    return;
+                const change = queue.shift() ?? terminal;
+                if (change === undefined) {
+                    interrupt();
+                    return;
+                }
+                if (!await o.permitted()) {
+                    interrupt();
+                    return;
+                }
+                controller.enqueue(frameFor(change));
+                sequence++;
+                // Pi: after an `error` change no calls follow.
+                if ('error' in change) {
+                    finished = true;
+                    signal?.removeEventListener('abort', interrupt);
+                    await close();
+                    controller.enqueue(encode({ requestId: o.requestId, sequence: sequence++, type: 'end' }));
+                    controller.close();
+                }
+            }
+            catch {
+                interrupt();
+            }
+        },
+        async cancel() { finished = true; signal?.removeEventListener('abort', interrupt); o.stop(); await close(); },
+    }, { highWaterMark: 1 });
+    return ok(new Response(body, { headers: { 'content-type': streamType, 'cache-control': 'no-store' } }));
+}
+/** Client side: consume an `opened` + `change` stream into Pi's `FileWatcher`. `deliver` is never called after `close` resolves. */
+export function watcherFromFrames(options) {
+    let stopped = false;
+    const deliver = (change) => { if (!stopped) {
+        try {
+            options.onChange(change);
+        }
+        catch { /* a throwing listener must not stop the watcher */ }
+    } };
+    void (async () => {
+        let sequence = 1;
+        try {
+            while (!stopped) {
+                const raw = await options.next();
+                if (stopped)
+                    return;
+                if (raw === undefined)
+                    throw new TypeError('Watch stream ended without a terminal frame');
+                const frame = streamFrame.parse(raw);
+                if (frame.requestId !== options.requestId || frame.sequence !== sequence++ || frame.type === 'opened')
+                    throw new TypeError('Watch frame sequence mismatch');
+                // The server sends `end` only after an `error` change; a bare `end` is a lost terminal error, never a quiet stop.
+                if (frame.type === 'end')
+                    throw new TypeError('Watch stream ended without an error change');
+                if (frame.type !== 'change')
+                    throw new TypeError('Unexpected watch frame');
+                const change = parseWatchChange(frame.change);
+                deliver(change);
+                if ('error' in change) {
+                    stopped = true;
+                    await options.dispose();
+                    return;
+                }
+            }
+        }
+        catch {
+            if (stopped)
+                return;
+            deliver({ error: new FileError('unknown', 'Remote file watch was interrupted') });
+            stopped = true;
+            await options.dispose();
+        }
+    })();
+    return { mode: options.mode, close: async () => { stopped = true; await options.dispose(); } };
+}

package/dist/remote-files.d.ts

@@ -0,0 +1,17 @@
+import type { FileSystem } from '@earendil-works/pi-durable/env';
+import type { WorkspaceIdentity, WorkspaceLease } from './contracts.js';
+export { createRemoteFileSystemHandler } from './remote-files-handler.js';
+export type { RemoteFileSystemAccess, RemoteFileSystemHandlerOptions } from './remote-files-handler.js';
+export type { RemoteFileSystemCall } from './remote-files-protocol.js';
+export interface RemoteFileSystemOptions {
+    readonly identity: WorkspaceIdentity;
+    readonly filesystemId: string;
+    readonly cwd: string;
+    readonly endpoint: string | URL;
+    readonly fetch: (request: Request) => Promise<Response>;
+    readonly maxRequestBytes?: number;
+    readonly maxResponseBytes?: number;
+    readonly maxFrameBytes?: number;
+}
+export declare function createRemoteFileSystemLease(options: RemoteFileSystemOptions): WorkspaceLease<FileSystem>;
+//# sourceMappingURL=remote-files.d.ts.map