@secure-exec/core 0.0.0-nathan-docs-sdk-expansion.c9c2e4e

package/dist/permissions.d.ts

@@ -0,0 +1,29 @@
+import * as protocol from "./generated-protocol.js";
+import { type LivePermissionMode } from "./protocol-maps.js";
+export type { LivePermissionMode } from "./protocol-maps.js";
+export interface LiveFsPermissionRule {
+    mode: LivePermissionMode;
+    operations?: string[];
+    paths?: string[];
+}
+export interface LivePatternPermissionRule {
+    mode: LivePermissionMode;
+    operations?: string[];
+    patterns?: string[];
+}
+export interface LiveRulePermissions<TRule> {
+    default?: LivePermissionMode;
+    rules: TRule[];
+}
+export type LivePermissionScope<TRule> = LivePermissionMode | LiveRulePermissions<TRule>;
+export interface LivePermissionsPolicy {
+    fs?: LivePermissionScope<LiveFsPermissionRule>;
+    network?: LivePermissionScope<LivePatternPermissionRule>;
+    child_process?: LivePermissionScope<LivePatternPermissionRule>;
+    process?: LivePermissionScope<LivePatternPermissionRule>;
+    env?: LivePermissionScope<LivePatternPermissionRule>;
+    tool?: LivePermissionScope<LivePatternPermissionRule>;
+}
+export declare function toGeneratedPermissionsPolicy(policy: LivePermissionsPolicy | undefined): protocol.PermissionsPolicy | null;
+export declare function toGeneratedFilesystemPermissionScope(scope: LivePermissionScope<LiveFsPermissionRule>): protocol.FsPermissionScope;
+export declare function toGeneratedPatternPermissionScope(scope: LivePermissionScope<LivePatternPermissionRule>): protocol.PatternPermissionScope;

package/dist/permissions.js

@@ -0,0 +1,68 @@
+import { toGeneratedPermissionMode, } from "./protocol-maps.js";
+export function toGeneratedPermissionsPolicy(policy) {
+    if (policy === undefined) {
+        return null;
+    }
+    return {
+        fs: policy.fs === undefined
+            ? null
+            : toGeneratedFilesystemPermissionScope(policy.fs),
+        network: policy.network === undefined
+            ? null
+            : toGeneratedPatternPermissionScope(policy.network),
+        childProcess: policy.child_process === undefined
+            ? null
+            : toGeneratedPatternPermissionScope(policy.child_process),
+        process: policy.process === undefined
+            ? null
+            : toGeneratedPatternPermissionScope(policy.process),
+        env: policy.env === undefined
+            ? null
+            : toGeneratedPatternPermissionScope(policy.env),
+        tool: policy.tool === undefined
+            ? null
+            : toGeneratedPatternPermissionScope(policy.tool),
+    };
+}
+export function toGeneratedFilesystemPermissionScope(scope) {
+    if (typeof scope === "string") {
+        return {
+            tag: "PermissionMode",
+            val: toGeneratedPermissionMode(scope),
+        };
+    }
+    return {
+        tag: "FsPermissionRuleSet",
+        val: {
+            default: scope.default === undefined
+                ? null
+                : toGeneratedPermissionMode(scope.default),
+            rules: scope.rules.map((rule) => ({
+                mode: toGeneratedPermissionMode(rule.mode),
+                operations: rule.operations ?? [],
+                paths: rule.paths ?? [],
+            })),
+        },
+    };
+}
+export function toGeneratedPatternPermissionScope(scope) {
+    if (typeof scope === "string") {
+        return {
+            tag: "PermissionMode",
+            val: toGeneratedPermissionMode(scope),
+        };
+    }
+    return {
+        tag: "PatternPermissionRuleSet",
+        val: {
+            default: scope.default === undefined
+                ? null
+                : toGeneratedPermissionMode(scope.default),
+            rules: scope.rules.map((rule) => ({
+                mode: toGeneratedPermissionMode(rule.mode),
+                operations: rule.operations ?? [],
+                patterns: rule.patterns ?? [],
+            })),
+        },
+    };
+}

package/dist/process.d.ts

@@ -0,0 +1,35 @@
+import { type ChildProcessWithoutNullStreams } from "node:child_process";
+export interface StdioSidecarProcessSpawnOptions {
+    command: string;
+    args?: string[];
+    cwd?: string;
+}
+export declare class SidecarProcessExited extends Error {
+    readonly exitCode: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly stderr: string;
+    constructor(options: {
+        exitCode: number | null;
+        signal: NodeJS.Signals | null;
+        stderr: string;
+    });
+}
+export declare class SidecarProcessError extends Error {
+    readonly childError: Error;
+    readonly stderr: string;
+    constructor(error: Error, stderr: string);
+}
+export declare class StdioSidecarProcess {
+    readonly child: ChildProcessWithoutNullStreams;
+    private readonly stderrChunks;
+    private readonly exitListeners;
+    private readonly errorListeners;
+    private constructor();
+    static spawn(options: StdioSidecarProcessSpawnOptions): StdioSidecarProcess;
+    static fromChild(child: ChildProcessWithoutNullStreams): StdioSidecarProcess;
+    onExit(handler: (error: SidecarProcessExited) => void): () => void;
+    onError(handler: (error: SidecarProcessError) => void): () => void;
+    stderrText(): string;
+    currentExitError(): SidecarProcessExited | null;
+    waitForExit(timeoutMs: number): Promise<number | null>;
+}

package/dist/process.js

@@ -0,0 +1,125 @@
+import { spawn, } from "node:child_process";
+function formatSidecarStderrSuffix(stderr) {
+    return stderr ? `\nstderr:\n${stderr}` : "";
+}
+export class SidecarProcessExited extends Error {
+    exitCode;
+    signal;
+    stderr;
+    constructor(options) {
+        const reason = options.signal !== null
+            ? `signal ${options.signal}`
+            : options.exitCode !== null
+                ? `code ${options.exitCode}`
+                : "disconnect";
+        super(`sidecar process exited with ${reason}${formatSidecarStderrSuffix(options.stderr)}`);
+        this.name = "SidecarProcessExited";
+        this.exitCode = options.exitCode;
+        this.signal = options.signal;
+        this.stderr = options.stderr;
+    }
+}
+export class SidecarProcessError extends Error {
+    childError;
+    stderr;
+    constructor(error, stderr) {
+        super(`sidecar process error: ${error.message}${formatSidecarStderrSuffix(stderr)}`);
+        this.name = "SidecarProcessError";
+        this.childError = error;
+        this.stderr = stderr;
+    }
+}
+export class StdioSidecarProcess {
+    child;
+    stderrChunks = [];
+    exitListeners = new Set();
+    errorListeners = new Set();
+    constructor(child) {
+        this.child = child;
+        this.child.stderr.on("data", (chunk) => {
+            this.stderrChunks.push(typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk));
+        });
+        this.child.on("exit", (code, signal) => {
+            const error = new SidecarProcessExited({
+                exitCode: code,
+                signal,
+                stderr: this.stderrText(),
+            });
+            for (const listener of this.exitListeners) {
+                listener(error);
+            }
+        });
+        this.child.on("error", (error) => {
+            const normalized = error instanceof Error ? error : new Error(String(error));
+            const sidecarError = new SidecarProcessError(normalized, this.stderrText());
+            for (const listener of this.errorListeners) {
+                listener(sidecarError);
+            }
+        });
+    }
+    static spawn(options) {
+        return new StdioSidecarProcess(spawn(options.command, options.args ?? [], {
+            cwd: options.cwd,
+            stdio: ["pipe", "pipe", "pipe"],
+        }));
+    }
+    static fromChild(child) {
+        return new StdioSidecarProcess(child);
+    }
+    onExit(handler) {
+        this.exitListeners.add(handler);
+        return () => {
+            this.exitListeners.delete(handler);
+        };
+    }
+    onError(handler) {
+        this.errorListeners.add(handler);
+        return () => {
+            this.errorListeners.delete(handler);
+        };
+    }
+    stderrText() {
+        return Buffer.concat(this.stderrChunks).toString("utf8").trim();
+    }
+    currentExitError() {
+        if (this.child.exitCode === null && this.child.signalCode === null) {
+            return null;
+        }
+        return new SidecarProcessExited({
+            exitCode: this.child.exitCode,
+            signal: this.child.signalCode,
+            stderr: this.stderrText(),
+        });
+    }
+    waitForExit(timeoutMs) {
+        return new Promise((resolve) => {
+            let timer = null;
+            const cleanup = () => {
+                this.child.off("exit", onExit);
+                this.child.off("close", onClose);
+                if (timer !== null) {
+                    clearTimeout(timer);
+                    timer = null;
+                }
+            };
+            const onExit = (code) => {
+                cleanup();
+                resolve(code);
+            };
+            const onClose = (code) => {
+                cleanup();
+                resolve(code);
+            };
+            if (this.child.exitCode !== null || this.child.signalCode !== null) {
+                resolve(this.child.exitCode);
+                return;
+            }
+            this.child.on("exit", onExit);
+            this.child.on("close", onClose);
+            timer = setTimeout(() => {
+                cleanup();
+                resolve(null);
+            }, timeoutMs);
+        });
+    }
+}

package/dist/protocol-client.d.ts

@@ -0,0 +1,46 @@
+import type { Readable, Writable } from "node:stream";
+import { type LiveSidecarEventSelector } from "./event-buffer.js";
+import { type LiveEventFrame, type LiveResponseFrame, type LiveSidecarRequestHandler, type ProtocolFramePayloadCodec } from "./protocol-frames.js";
+import type { LiveOwnershipScope } from "./ownership.js";
+import type { LiveRequestPayload } from "./request-payloads.js";
+export interface SidecarProtocolClientOptions {
+    stdin: Writable;
+    stdout: Readable;
+    frameTimeoutMs: number;
+    eventBufferCapacity: number;
+    payloadCodec?: ProtocolFramePayloadCodec;
+    stderrText?: () => string;
+    frameError?: (error: Error) => Error;
+    streamEndedError?: () => Error;
+}
+export declare class SidecarProtocolClient {
+    private readonly eventBuffer;
+    private readonly eventListeners;
+    private readonly frameTimeoutMs;
+    private readonly payloadCodec;
+    private readonly stderrText;
+    private readonly hostFrameFactory;
+    private readonly frameTransport;
+    private closedError;
+    private readonly eventWaiters;
+    private sidecarRequestHandler;
+    constructor(options: SidecarProtocolClientOptions);
+    setSidecarRequestHandler(handler: LiveSidecarRequestHandler | null): void;
+    onEvent(handler: (event: LiveEventFrame) => void): () => void;
+    sendRequest(input: {
+        ownership: LiveOwnershipScope;
+        payload: LiveRequestPayload;
+    }): Promise<LiveResponseFrame>;
+    waitForEvent(matcher: LiveSidecarEventSelector | ((event: LiveEventFrame) => boolean), timeoutMs?: number, options?: {
+        signal?: AbortSignal;
+    }): Promise<LiveEventFrame>;
+    failPermanently(error: Error, options?: {
+        replaceExisting?: (current: Error, next: Error) => boolean;
+    }): void;
+    dispose(): void;
+    private writeFrame;
+    private dispatchSidecarRequest;
+    private dispatchEvent;
+    private bufferEvent;
+    private rejectPending;
+}

package/dist/protocol-client.js

@@ -0,0 +1,180 @@
+import { SidecarEventBuffer, SidecarEventBufferOverflow, normalizeSidecarEventMatcher, sidecarEventWaitAbortError, } from "./event-buffer.js";
+import { FrameRpcTransport } from "./frame-rpc.js";
+import { HostProtocolFrameFactory, classifySidecarWrittenProtocolFrame, decodeProtocolFramePayload, encodeProtocolFramePayload, resolveSidecarRequestFramePayload, } from "./protocol-frames.js";
+export class SidecarProtocolClient {
+    eventBuffer;
+    eventListeners = new Set();
+    frameTimeoutMs;
+    payloadCodec;
+    stderrText;
+    hostFrameFactory = new HostProtocolFrameFactory();
+    frameTransport;
+    closedError = null;
+    eventWaiters = new Set();
+    sidecarRequestHandler = null;
+    constructor(options) {
+        this.frameTimeoutMs = options.frameTimeoutMs;
+        this.eventBuffer = new SidecarEventBuffer(options.eventBufferCapacity);
+        this.payloadCodec = options.payloadCodec ?? "bare";
+        this.stderrText = options.stderrText ?? (() => "");
+        this.frameTransport = new FrameRpcTransport({
+            stdin: options.stdin,
+            stdout: options.stdout,
+            encodeFrame: (frame) => encodeProtocolFramePayload(frame, this.payloadCodec),
+            decodeFrame: (payload) => decodeProtocolFramePayload(payload, this.payloadCodec),
+            classifyFrame: classifySidecarWrittenProtocolFrame,
+        });
+        this.frameTransport.onEvent((event) => {
+            this.dispatchEvent(event);
+        });
+        this.frameTransport.onSidecarRequest((request) => {
+            void this.dispatchSidecarRequest(request);
+        });
+        this.frameTransport.onError((error) => {
+            this.failPermanently(options.frameError?.(error) ?? error);
+        });
+        this.frameTransport.onEnd(() => {
+            this.failPermanently(options.streamEndedError?.() ??
+                new Error("sidecar protocol stream ended"));
+        });
+    }
+    setSidecarRequestHandler(handler) {
+        this.sidecarRequestHandler = handler;
+    }
+    onEvent(handler) {
+        this.eventListeners.add(handler);
+        return () => {
+            this.eventListeners.delete(handler);
+        };
+    }
+    async sendRequest(input) {
+        if (this.closedError) {
+            throw this.closedError;
+        }
+        const request = this.hostFrameFactory.createRequestFrame(input);
+        const response = await this.frameTransport.sendFrame(request.request_id, request, {
+            timeoutMs: this.frameTimeoutMs,
+            timeoutMessage: () => `timed out waiting for sidecar protocol frame for ${input.payload.type}\nstderr:\n${this.stderrText()}`,
+        });
+        if (response.payload.type === "rejected") {
+            throw new Error(`sidecar rejected request ${request.request_id}: ${response.payload.code}: ${response.payload.message}`);
+        }
+        return response;
+    }
+    async waitForEvent(matcher, timeoutMs, options) {
+        if (this.closedError instanceof SidecarEventBufferOverflow) {
+            throw this.closedError;
+        }
+        const normalizedMatcher = normalizeSidecarEventMatcher(matcher);
+        const bufferedEvent = this.eventBuffer.take(normalizedMatcher);
+        if (bufferedEvent) {
+            return bufferedEvent;
+        }
+        if (this.closedError) {
+            throw this.closedError;
+        }
+        if (options?.signal?.aborted) {
+            throw sidecarEventWaitAbortError(options.signal.reason);
+        }
+        return await new Promise((resolve, reject) => {
+            let abortListener = null;
+            const waiter = {
+                matches: normalizedMatcher.matches,
+                resolve: (event) => {
+                    if (waiter.timer !== null) {
+                        clearTimeout(waiter.timer);
+                    }
+                    if (abortListener) {
+                        options?.signal?.removeEventListener("abort", abortListener);
+                        abortListener = null;
+                    }
+                    this.eventWaiters.delete(waiter);
+                    resolve(event);
+                },
+                reject: (error) => {
+                    if (waiter.timer !== null) {
+                        clearTimeout(waiter.timer);
+                    }
+                    if (abortListener) {
+                        options?.signal?.removeEventListener("abort", abortListener);
+                        abortListener = null;
+                    }
+                    this.eventWaiters.delete(waiter);
+                    reject(error);
+                },
+                timer: timeoutMs === undefined
+                    ? null
+                    : setTimeout(() => {
+                        this.eventWaiters.delete(waiter);
+                        reject(new Error(`timed out waiting for sidecar event\nstderr:\n${this.stderrText()}`));
+                    }, timeoutMs),
+            };
+            if (options?.signal) {
+                abortListener = () => {
+                    waiter.reject(sidecarEventWaitAbortError(options.signal?.reason));
+                };
+                options.signal.addEventListener("abort", abortListener, { once: true });
+            }
+            this.eventWaiters.add(waiter);
+        });
+    }
+    failPermanently(error, options) {
+        if (this.closedError) {
+            if (!options?.replaceExisting?.(this.closedError, error)) {
+                return;
+            }
+        }
+        this.closedError = error;
+        this.rejectPending(error);
+    }
+    dispose() {
+        this.frameTransport.dispose();
+    }
+    async writeFrame(frame) {
+        await this.frameTransport.writeFrame(frame);
+    }
+    async dispatchSidecarRequest(request) {
+        const payload = await resolveSidecarRequestFramePayload(request, this.sidecarRequestHandler);
+        try {
+            await this.writeFrame(this.hostFrameFactory.createSidecarResponseFrame({
+                request,
+                payload,
+            }));
+        }
+        catch (error) {
+            const normalized = error instanceof Error ? error : new Error(String(error));
+            this.failPermanently(normalized);
+        }
+    }
+    dispatchEvent(event) {
+        for (const listener of this.eventListeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Event listeners are best-effort observers and must not break framing.
+            }
+        }
+        for (const waiter of this.eventWaiters) {
+            if (!waiter.matches(event)) {
+                continue;
+            }
+            waiter.resolve(event);
+            return;
+        }
+        this.bufferEvent(event);
+    }
+    bufferEvent(event) {
+        const overflow = this.eventBuffer.buffer(event);
+        if (overflow) {
+            this.failPermanently(overflow);
+        }
+    }
+    rejectPending(error) {
+        this.frameTransport.rejectAll(error);
+        for (const waiter of this.eventWaiters) {
+            waiter.reject(error);
+        }
+        this.eventWaiters.clear();
+    }
+}

package/dist/protocol-frames.d.ts

@@ -0,0 +1,68 @@
+import { type TransportPayloadCodec } from "./frame-payload-codec.js";
+import type { ClassifiedFrame } from "./frame-rpc.js";
+import { type LiveSidecarRequestPayload, type LiveSidecarResponsePayload } from "./callbacks.js";
+import { type LiveSidecarEventPayload } from "./event-buffer.js";
+import * as protocol from "./generated-protocol.js";
+import { type LiveOwnershipScope } from "./ownership.js";
+import { SIDECAR_PROTOCOL_SCHEMA } from "./protocol-schema.js";
+import { type LiveRequestPayload } from "./request-payloads.js";
+import { type LiveResponsePayload } from "./response-payloads.js";
+export interface LiveRequestFrame {
+    frame_type: "request";
+    schema: typeof SIDECAR_PROTOCOL_SCHEMA;
+    request_id: number;
+    ownership: LiveOwnershipScope;
+    payload: LiveRequestPayload;
+}
+export interface LiveEventFrame {
+    frame_type: "event";
+    schema: typeof SIDECAR_PROTOCOL_SCHEMA;
+    ownership: LiveOwnershipScope;
+    payload: LiveSidecarEventPayload;
+}
+export interface LiveSidecarRequestFrame {
+    frame_type: "sidecar_request";
+    schema: typeof SIDECAR_PROTOCOL_SCHEMA;
+    request_id: number;
+    ownership: LiveOwnershipScope;
+    payload: LiveSidecarRequestPayload;
+}
+export interface LiveResponseFrame {
+    frame_type: "response";
+    schema: typeof SIDECAR_PROTOCOL_SCHEMA;
+    request_id: number;
+    ownership: LiveOwnershipScope;
+    payload: LiveResponsePayload;
+}
+export interface LiveSidecarResponseFrame {
+    frame_type: "sidecar_response";
+    schema: typeof SIDECAR_PROTOCOL_SCHEMA;
+    request_id: number;
+    ownership: LiveOwnershipScope;
+    payload: LiveSidecarResponsePayload;
+}
+export type LiveProtocolFrame = LiveRequestFrame | LiveResponseFrame | LiveEventFrame | LiveSidecarRequestFrame | LiveSidecarResponseFrame;
+export type LiveSidecarWrittenProtocolFrame = LiveResponseFrame | LiveEventFrame | LiveSidecarRequestFrame;
+export type ProtocolFramePayloadCodec = TransportPayloadCodec;
+export type ClassifiedSidecarWrittenProtocolFrame = ClassifiedFrame<LiveResponseFrame, LiveEventFrame, LiveSidecarRequestFrame>;
+export type LiveSidecarRequestHandler = (request: LiveSidecarRequestFrame) => Promise<LiveSidecarResponsePayload> | LiveSidecarResponsePayload;
+export declare class HostProtocolFrameFactory {
+    private nextRequestId;
+    createRequestFrame(input: {
+        ownership: LiveOwnershipScope;
+        payload: LiveRequestPayload;
+    }): LiveRequestFrame;
+    createSidecarResponseFrame(input: {
+        request: LiveSidecarRequestFrame;
+        payload: LiveSidecarResponsePayload;
+    }): LiveSidecarResponseFrame;
+}
+export declare function resolveSidecarRequestFramePayload(request: LiveSidecarRequestFrame, handler: LiveSidecarRequestHandler | null): Promise<LiveSidecarResponsePayload>;
+export declare function toGeneratedProtocolFrame(frame: LiveProtocolFrame): protocol.ProtocolFrame;
+export declare function encodeBareProtocolFrame(frame: LiveProtocolFrame): Buffer;
+export declare function decodeBareProtocolFrame(payload: Uint8Array): LiveSidecarWrittenProtocolFrame;
+export declare function encodeProtocolFramePayload(frame: LiveProtocolFrame, codec: ProtocolFramePayloadCodec): Buffer;
+export declare function decodeProtocolFramePayload(payload: Uint8Array, codec: ProtocolFramePayloadCodec): LiveSidecarWrittenProtocolFrame;
+export declare function classifySidecarWrittenProtocolFrame(frame: LiveSidecarWrittenProtocolFrame): ClassifiedSidecarWrittenProtocolFrame;
+export declare function fromGeneratedSidecarWrittenProtocolFrame(frame: protocol.ProtocolFrame): LiveSidecarWrittenProtocolFrame;
+export declare function toLiveProtocolSchema(schema: protocol.ProtocolSchema): typeof SIDECAR_PROTOCOL_SCHEMA;