@evalops/maestro 0.10.8 → 0.10.11

package/dist/utils/downstream-http.js

@@ -0,0 +1,151 @@
+import { createLogger } from "./logger.js";
+import { parseRetryAfter } from "./retry.js";
+const logger = createLogger("runtime:downstream-http");
+export class DownstreamHttpError extends Error {
+    constructor(message, serviceName, failureMode, retryable, timeoutMs) {
+        super(message);
+        this.serviceName = serviceName;
+        this.failureMode = failureMode;
+        this.retryable = retryable;
+        this.timeoutMs = timeoutMs;
+        this.name = "DownstreamHttpError";
+    }
+}
+function sleep(delayMs) {
+    return new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+function defaultShouldRetryStatus(status) {
+    return status === 408 || status === 429 || status >= 500;
+}
+function isRetryableFetchError(error) {
+    if (error.name === "AbortError") {
+        return true;
+    }
+    const message = error.message.toLowerCase();
+    return (message.includes("timeout") ||
+        message.includes("network") ||
+        message.includes("econnreset") ||
+        message.includes("etimedout") ||
+        message.includes("econnrefused") ||
+        message.includes("socket hang up") ||
+        message.includes("fetch failed"));
+}
+function normalizePositiveInt(value, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return fallback;
+    }
+    return Math.max(1, Math.trunc(value));
+}
+function normalizeDelay(value, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        return fallback;
+    }
+    return Math.trunc(value);
+}
+function combineAbortSignals(signals) {
+    const controller = new AbortController();
+    const abortFrom = (signal) => {
+        if (!controller.signal.aborted) {
+            controller.abort(signal.reason);
+        }
+    };
+    for (const signal of signals) {
+        if (signal.aborted) {
+            abortFrom(signal);
+            break;
+        }
+        signal.addEventListener("abort", () => abortFrom(signal), { once: true });
+    }
+    return controller.signal;
+}
+function collectRetryHeaders(response) {
+    const headers = {};
+    const retryAfter = response.headers.get("retry-after");
+    const retryAfterMs = response.headers.get("retry-after-ms");
+    if (retryAfter) {
+        headers["retry-after"] = retryAfter;
+    }
+    if (retryAfterMs) {
+        headers["retry-after-ms"] = retryAfterMs;
+    }
+    return headers;
+}
+function retryDelayMs(response, attemptIndex, initialDelayMs, maxDelayMs) {
+    const retryAfterMs = parseRetryAfter(collectRetryHeaders(response));
+    if (retryAfterMs !== null) {
+        return Math.min(retryAfterMs, maxDelayMs);
+    }
+    return Math.min(initialDelayMs * 2 ** attemptIndex, maxDelayMs);
+}
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function timeoutError(serviceName, failureMode, timeoutMs) {
+    return new DownstreamHttpError(`${serviceName} request timed out after ${timeoutMs}ms`, serviceName, failureMode, true, timeoutMs);
+}
+function requestError(serviceName, failureMode, error, retryable) {
+    return new DownstreamHttpError(`${serviceName} request failed: ${error.message}`, serviceName, failureMode, retryable);
+}
+export async function fetchDownstream(input, init, options) {
+    const maxAttempts = normalizePositiveInt(options.maxAttempts, 2);
+    const initialDelayMs = normalizeDelay(options.initialDelayMs, 100);
+    const maxDelayMs = normalizeDelay(options.maxDelayMs, 1_000);
+    const timeoutMs = normalizePositiveInt(options.timeoutMs, 2_000);
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const sleepImpl = options.sleepMs ?? sleep;
+    const shouldRetryStatus = options.shouldRetryStatus ?? defaultShouldRetryStatus;
+    const externalSignal = init.signal;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const timeoutController = new AbortController();
+        const timeout = setTimeout(() => timeoutController.abort(), timeoutMs);
+        const signal = externalSignal
+            ? combineAbortSignals([externalSignal, timeoutController.signal])
+            : timeoutController.signal;
+        try {
+            const response = await fetchImpl(input, { ...init, signal });
+            clearTimeout(timeout);
+            if (response.ok ||
+                !shouldRetryStatus(response.status) ||
+                attempt >= maxAttempts) {
+                return response;
+            }
+            const delayMs = retryDelayMs(response, attempt - 1, initialDelayMs, maxDelayMs);
+            logger.debug("Retrying downstream request after status", {
+                serviceName: options.serviceName,
+                failureMode: options.failureMode,
+                status: response.status,
+                attempt,
+                maxAttempts,
+                delayMs,
+            });
+            await sleepImpl(delayMs);
+        }
+        catch (error) {
+            clearTimeout(timeout);
+            const normalized = toError(error);
+            const timedOut = timeoutController.signal.aborted;
+            if (externalSignal?.aborted && !timedOut) {
+                throw normalized;
+            }
+            const retryable = timedOut || isRetryableFetchError(normalized);
+            const wrapped = timedOut
+                ? timeoutError(options.serviceName, options.failureMode, timeoutMs)
+                : requestError(options.serviceName, options.failureMode, normalized, retryable);
+            if (!retryable || attempt >= maxAttempts) {
+                throw wrapped;
+            }
+            const delayMs = Math.min(initialDelayMs * 2 ** (attempt - 1), maxDelayMs);
+            logger.debug("Retrying downstream request after error", {
+                serviceName: options.serviceName,
+                failureMode: options.failureMode,
+                error: wrapped.message,
+                attempt,
+                maxAttempts,
+                delayMs,
+            });
+            await sleepImpl(delayMs);
+        }
+    }
+    throw new DownstreamHttpError(`${options.serviceName} request failed after ${maxAttempts} attempts`, options.serviceName, options.failureMode, true);
+}
+//# sourceMappingURL=downstream-http.js.map

package/dist/utils/downstream-http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"downstream-http.js","sourceRoot":"","sources":["../../src/utils/downstream-http.ts"],"names":[],"mappings":"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","sourcesContent":["import { createLogger } from \"./logger.js\";\nimport { parseRetryAfter } from \"./retry.js\";\n\nconst logger = createLogger(\"runtime:downstream-http\");\n\nexport type DownstreamFailureMode = \"required\" | \"optional\";\n\nexport interface DownstreamFetchOptions {\n\tserviceName: string;\n\tfailureMode: DownstreamFailureMode;\n\ttimeoutMs: number;\n\tmaxAttempts?: number;\n\tinitialDelayMs?: number;\n\tmaxDelayMs?: number;\n\tfetchImpl?: typeof fetch;\n\tsleepMs?: (delayMs: number) => Promise<void>;\n\tshouldRetryStatus?: (status: number) => boolean;\n}\n\nexport class DownstreamHttpError extends Error {\n\tconstructor(\n\t\tmessage: string,\n\t\tpublic readonly serviceName: string,\n\t\tpublic readonly failureMode: DownstreamFailureMode,\n\t\tpublic readonly retryable: boolean,\n\t\tpublic readonly timeoutMs?: number,\n\t) {\n\t\tsuper(message);\n\t\tthis.name = \"DownstreamHttpError\";\n\t}\n}\n\nfunction sleep(delayMs: number): Promise<void> {\n\treturn new Promise((resolve) => setTimeout(resolve, delayMs));\n}\n\nfunction defaultShouldRetryStatus(status: number): boolean {\n\treturn status === 408 || status === 429 || status >= 500;\n}\n\nfunction isRetryableFetchError(error: Error): boolean {\n\tif (error.name === \"AbortError\") {\n\t\treturn true;\n\t}\n\n\tconst message = error.message.toLowerCase();\n\treturn (\n\t\tmessage.includes(\"timeout\") ||\n\t\tmessage.includes(\"network\") ||\n\t\tmessage.includes(\"econnreset\") ||\n\t\tmessage.includes(\"etimedout\") ||\n\t\tmessage.includes(\"econnrefused\") ||\n\t\tmessage.includes(\"socket hang up\") ||\n\t\tmessage.includes(\"fetch failed\")\n\t);\n}\n\nfunction normalizePositiveInt(\n\tvalue: number | undefined,\n\tfallback: number,\n): number {\n\tif (typeof value !== \"number\" || !Number.isFinite(value)) {\n\t\treturn fallback;\n\t}\n\treturn Math.max(1, Math.trunc(value));\n}\n\nfunction normalizeDelay(value: number | undefined, fallback: number): number {\n\tif (typeof value !== \"number\" || !Number.isFinite(value) || value < 0) {\n\t\treturn fallback;\n\t}\n\treturn Math.trunc(value);\n}\n\nfunction combineAbortSignals(signals: AbortSignal[]): AbortSignal {\n\tconst controller = new AbortController();\n\tconst abortFrom = (signal: AbortSignal) => {\n\t\tif (!controller.signal.aborted) {\n\t\t\tcontroller.abort(signal.reason);\n\t\t}\n\t};\n\n\tfor (const signal of signals) {\n\t\tif (signal.aborted) {\n\t\t\tabortFrom(signal);\n\t\t\tbreak;\n\t\t}\n\t\tsignal.addEventListener(\"abort\", () => abortFrom(signal), { once: true });\n\t}\n\n\treturn controller.signal;\n}\n\nfunction collectRetryHeaders(response: Response): Record<string, string> {\n\tconst headers: Record<string, string> = {};\n\tconst retryAfter = response.headers.get(\"retry-after\");\n\tconst retryAfterMs = response.headers.get(\"retry-after-ms\");\n\tif (retryAfter) {\n\t\theaders[\"retry-after\"] = retryAfter;\n\t}\n\tif (retryAfterMs) {\n\t\theaders[\"retry-after-ms\"] = retryAfterMs;\n\t}\n\treturn headers;\n}\n\nfunction retryDelayMs(\n\tresponse: Response,\n\tattemptIndex: number,\n\tinitialDelayMs: number,\n\tmaxDelayMs: number,\n): number {\n\tconst retryAfterMs = parseRetryAfter(collectRetryHeaders(response));\n\tif (retryAfterMs !== null) {\n\t\treturn Math.min(retryAfterMs, maxDelayMs);\n\t}\n\n\treturn Math.min(initialDelayMs * 2 ** attemptIndex, maxDelayMs);\n}\n\nfunction toError(error: unknown): Error {\n\treturn error instanceof Error ? error : new Error(String(error));\n}\n\nfunction timeoutError(\n\tserviceName: string,\n\tfailureMode: DownstreamFailureMode,\n\ttimeoutMs: number,\n): DownstreamHttpError {\n\treturn new DownstreamHttpError(\n\t\t`${serviceName} request timed out after ${timeoutMs}ms`,\n\t\tserviceName,\n\t\tfailureMode,\n\t\ttrue,\n\t\ttimeoutMs,\n\t);\n}\n\nfunction requestError(\n\tserviceName: string,\n\tfailureMode: DownstreamFailureMode,\n\terror: Error,\n\tretryable: boolean,\n): DownstreamHttpError {\n\treturn new DownstreamHttpError(\n\t\t`${serviceName} request failed: ${error.message}`,\n\t\tserviceName,\n\t\tfailureMode,\n\t\tretryable,\n\t);\n}\n\nexport async function fetchDownstream(\n\tinput: Parameters<typeof fetch>[0],\n\tinit: RequestInit,\n\toptions: DownstreamFetchOptions,\n): Promise<Response> {\n\tconst maxAttempts = normalizePositiveInt(options.maxAttempts, 2);\n\tconst initialDelayMs = normalizeDelay(options.initialDelayMs, 100);\n\tconst maxDelayMs = normalizeDelay(options.maxDelayMs, 1_000);\n\tconst timeoutMs = normalizePositiveInt(options.timeoutMs, 2_000);\n\tconst fetchImpl = options.fetchImpl ?? fetch;\n\tconst sleepImpl = options.sleepMs ?? sleep;\n\tconst shouldRetryStatus =\n\t\toptions.shouldRetryStatus ?? defaultShouldRetryStatus;\n\tconst externalSignal = init.signal;\n\n\tfor (let attempt = 1; attempt <= maxAttempts; attempt++) {\n\t\tconst timeoutController = new AbortController();\n\t\tconst timeout = setTimeout(() => timeoutController.abort(), timeoutMs);\n\t\tconst signal = externalSignal\n\t\t\t? combineAbortSignals([externalSignal, timeoutController.signal])\n\t\t\t: timeoutController.signal;\n\n\t\ttry {\n\t\t\tconst response = await fetchImpl(input, { ...init, signal });\n\t\t\tclearTimeout(timeout);\n\n\t\t\tif (\n\t\t\t\tresponse.ok ||\n\t\t\t\t!shouldRetryStatus(response.status) ||\n\t\t\t\tattempt >= maxAttempts\n\t\t\t) {\n\t\t\t\treturn response;\n\t\t\t}\n\n\t\t\tconst delayMs = retryDelayMs(\n\t\t\t\tresponse,\n\t\t\t\tattempt - 1,\n\t\t\t\tinitialDelayMs,\n\t\t\t\tmaxDelayMs,\n\t\t\t);\n\t\t\tlogger.debug(\"Retrying downstream request after status\", {\n\t\t\t\tserviceName: options.serviceName,\n\t\t\t\tfailureMode: options.failureMode,\n\t\t\t\tstatus: response.status,\n\t\t\t\tattempt,\n\t\t\t\tmaxAttempts,\n\t\t\t\tdelayMs,\n\t\t\t});\n\t\t\tawait sleepImpl(delayMs);\n\t\t} catch (error) {\n\t\t\tclearTimeout(timeout);\n\t\t\tconst normalized = toError(error);\n\t\t\tconst timedOut = timeoutController.signal.aborted;\n\t\t\tif (externalSignal?.aborted && !timedOut) {\n\t\t\t\tthrow normalized;\n\t\t\t}\n\n\t\t\tconst retryable = timedOut || isRetryableFetchError(normalized);\n\t\t\tconst wrapped = timedOut\n\t\t\t\t? timeoutError(options.serviceName, options.failureMode, timeoutMs)\n\t\t\t\t: requestError(\n\t\t\t\t\t\toptions.serviceName,\n\t\t\t\t\t\toptions.failureMode,\n\t\t\t\t\t\tnormalized,\n\t\t\t\t\t\tretryable,\n\t\t\t\t\t);\n\n\t\t\tif (!retryable || attempt >= maxAttempts) {\n\t\t\t\tthrow wrapped;\n\t\t\t}\n\n\t\t\tconst delayMs = Math.min(initialDelayMs * 2 ** (attempt - 1), maxDelayMs);\n\t\t\tlogger.debug(\"Retrying downstream request after error\", {\n\t\t\t\tserviceName: options.serviceName,\n\t\t\t\tfailureMode: options.failureMode,\n\t\t\t\terror: wrapped.message,\n\t\t\t\tattempt,\n\t\t\t\tmaxAttempts,\n\t\t\t\tdelayMs,\n\t\t\t});\n\t\t\tawait sleepImpl(delayMs);\n\t\t}\n\t}\n\n\tthrow new DownstreamHttpError(\n\t\t`${options.serviceName} request failed after ${maxAttempts} attempts`,\n\t\toptions.serviceName,\n\t\toptions.failureMode,\n\t\ttrue,\n\t);\n}\n"]}

package/dist/utils/downstream.d.ts

@@ -0,0 +1,18 @@
+import { CircuitBreaker, type CircuitBreakerConfig } from "../safety/circuit-breaker.js";
+export declare const FailClosed = "fail-closed";
+export declare const FailOpen = "fail-open";
+export type DownstreamFailureMode = typeof FailClosed | typeof FailOpen;
+export interface DownstreamConfig {
+    failureMode: DownstreamFailureMode;
+    breaker?: CircuitBreaker | Partial<CircuitBreakerConfig> | false;
+}
+export declare class DownstreamClient {
+    readonly name: string;
+    readonly failureMode: DownstreamFailureMode;
+    private readonly breaker?;
+    constructor(name: string, config: DownstreamConfig);
+    callOp<T>(op: string, fn: () => Promise<T>, failOpenValue: () => T): Promise<T>;
+}
+export declare function New(name: string, config: DownstreamConfig): DownstreamClient;
+export declare function CallOp<T>(client: DownstreamClient, op: string, fn: () => Promise<T>, failOpenValue: () => T): Promise<T>;
+//# sourceMappingURL=downstream.d.ts.map

package/dist/utils/downstream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"downstream.d.ts","sourceRoot":"","sources":["../../src/utils/downstream.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,cAAc,EACd,KAAK,oBAAoB,EACzB,MAAM,8BAA8B,CAAC;AAKtC,eAAO,MAAM,UAAU,gBAAgB,CAAC;AACxC,eAAO,MAAM,QAAQ,cAAc,CAAC;AAEpC,MAAM,MAAM,qBAAqB,GAAG,OAAO,UAAU,GAAG,OAAO,QAAQ,CAAC;AAExE,MAAM,WAAW,gBAAgB;IAChC,WAAW,EAAE,qBAAqB,CAAC;IACnC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,oBAAoB,CAAC,GAAG,KAAK,CAAC;CACjE;AAED,qBAAa,gBAAgB;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,qBAAqB,CAAC;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAiB;gBAE9B,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB;IAe5C,MAAM,CAAC,CAAC,EACb,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,aAAa,EAAE,MAAM,CAAC,GACpB,OAAO,CAAC,CAAC,CAAC;CAoBb;AAED,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAE5E;AAED,wBAAgB,MAAM,CAAC,CAAC,EACvB,MAAM,EAAE,gBAAgB,EACxB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,aAAa,EAAE,MAAM,CAAC,GACpB,OAAO,CAAC,CAAC,CAAC,CAEZ"}

package/dist/utils/downstream.js

@@ -0,0 +1,47 @@
+import { CircuitBreaker, } from "../safety/circuit-breaker.js";
+import { createLogger } from "./logger.js";
+const logger = createLogger("runtime:downstream");
+export const FailClosed = "fail-closed";
+export const FailOpen = "fail-open";
+export class DownstreamClient {
+    constructor(name, config) {
+        this.name = name;
+        this.failureMode = config.failureMode;
+        if (config.breaker === false || config.breaker === undefined) {
+            this.breaker = undefined;
+        }
+        else if (config.breaker instanceof CircuitBreaker) {
+            this.breaker = config.breaker;
+        }
+        else {
+            this.breaker = new CircuitBreaker({
+                ...config.breaker,
+                toolName: config.breaker.toolName ?? name,
+            });
+        }
+    }
+    async callOp(op, fn, failOpenValue) {
+        try {
+            return this.breaker ? await this.breaker.execute(fn) : await fn();
+        }
+        catch (error) {
+            if (this.failureMode === FailOpen) {
+                logger.warn("Downstream call failed (fail-open)", {
+                    downstream: this.name,
+                    op,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                return failOpenValue();
+            }
+            logger.error("Downstream call failed (fail-closed)", error instanceof Error ? error : new Error(String(error)), { downstream: this.name, op });
+            throw error;
+        }
+    }
+}
+export function New(name, config) {
+    return new DownstreamClient(name, config);
+}
+export function CallOp(client, op, fn, failOpenValue) {
+    return client.callOp(op, fn, failOpenValue);
+}
+//# sourceMappingURL=downstream.js.map

package/dist/utils/downstream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"downstream.js","sourceRoot":"","sources":["../../src/utils/downstream.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,cAAc,GAEd,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,MAAM,GAAG,YAAY,CAAC,oBAAoB,CAAC,CAAC;AAElD,MAAM,CAAC,MAAM,UAAU,GAAG,aAAa,CAAC;AACxC,MAAM,CAAC,MAAM,QAAQ,GAAG,WAAW,CAAC;AASpC,MAAM,OAAO,gBAAgB;IAK5B,YAAY,IAAY,EAAE,MAAwB;QACjD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;QACtC,IAAI,MAAM,CAAC,OAAO,KAAK,KAAK,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC9D,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;QAC1B,CAAC;aAAM,IAAI,MAAM,CAAC,OAAO,YAAY,cAAc,EAAE,CAAC;YACrD,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC/B,CAAC;aAAM,CAAC;YACP,IAAI,CAAC,OAAO,GAAG,IAAI,cAAc,CAAC;gBACjC,GAAG,MAAM,CAAC,OAAO;gBACjB,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,QAAQ,IAAI,IAAI;aACzC,CAAC,CAAC;QACJ,CAAC;IACF,CAAC;IAED,KAAK,CAAC,MAAM,CACX,EAAU,EACV,EAAoB,EACpB,aAAsB;QAEtB,IAAI,CAAC;YACJ,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;QACnE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,IAAI,CAAC,WAAW,KAAK,QAAQ,EAAE,CAAC;gBACnC,MAAM,CAAC,IAAI,CAAC,oCAAoC,EAAE;oBACjD,UAAU,EAAE,IAAI,CAAC,IAAI;oBACrB,EAAE;oBACF,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;iBAC7D,CAAC,CAAC;gBACH,OAAO,aAAa,EAAE,CAAC;YACxB,CAAC;YACD,MAAM,CAAC,KAAK,CACX,sCAAsC,EACtC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EACzD,EAAE,UAAU,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,CAC7B,CAAC;YACF,MAAM,KAAK,CAAC;QACb,CAAC;IACF,CAAC;CACD;AAED,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,MAAwB;IACzD,OAAO,IAAI,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,MAAM,CACrB,MAAwB,EACxB,EAAU,EACV,EAAoB,EACpB,aAAsB;IAEtB,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,aAAa,CAAC,CAAC;AAC7C,CAAC","sourcesContent":["import {\n\tCircuitBreaker,\n\ttype CircuitBreakerConfig,\n} from \"../safety/circuit-breaker.js\";\nimport { createLogger } from \"./logger.js\";\n\nconst logger = createLogger(\"runtime:downstream\");\n\nexport const FailClosed = \"fail-closed\";\nexport const FailOpen = \"fail-open\";\n\nexport type DownstreamFailureMode = typeof FailClosed | typeof FailOpen;\n\nexport interface DownstreamConfig {\n\tfailureMode: DownstreamFailureMode;\n\tbreaker?: CircuitBreaker | Partial<CircuitBreakerConfig> | false;\n}\n\nexport class DownstreamClient {\n\treadonly name: string;\n\treadonly failureMode: DownstreamFailureMode;\n\tprivate readonly breaker?: CircuitBreaker;\n\n\tconstructor(name: string, config: DownstreamConfig) {\n\t\tthis.name = name;\n\t\tthis.failureMode = config.failureMode;\n\t\tif (config.breaker === false || config.breaker === undefined) {\n\t\t\tthis.breaker = undefined;\n\t\t} else if (config.breaker instanceof CircuitBreaker) {\n\t\t\tthis.breaker = config.breaker;\n\t\t} else {\n\t\t\tthis.breaker = new CircuitBreaker({\n\t\t\t\t...config.breaker,\n\t\t\t\ttoolName: config.breaker.toolName ?? name,\n\t\t\t});\n\t\t}\n\t}\n\n\tasync callOp<T>(\n\t\top: string,\n\t\tfn: () => Promise<T>,\n\t\tfailOpenValue: () => T,\n\t): Promise<T> {\n\t\ttry {\n\t\t\treturn this.breaker ? await this.breaker.execute(fn) : await fn();\n\t\t} catch (error) {\n\t\t\tif (this.failureMode === FailOpen) {\n\t\t\t\tlogger.warn(\"Downstream call failed (fail-open)\", {\n\t\t\t\t\tdownstream: this.name,\n\t\t\t\t\top,\n\t\t\t\t\terror: error instanceof Error ? error.message : String(error),\n\t\t\t\t});\n\t\t\t\treturn failOpenValue();\n\t\t\t}\n\t\t\tlogger.error(\n\t\t\t\t\"Downstream call failed (fail-closed)\",\n\t\t\t\terror instanceof Error ? error : new Error(String(error)),\n\t\t\t\t{ downstream: this.name, op },\n\t\t\t);\n\t\t\tthrow error;\n\t\t}\n\t}\n}\n\nexport function New(name: string, config: DownstreamConfig): DownstreamClient {\n\treturn new DownstreamClient(name, config);\n}\n\nexport function CallOp<T>(\n\tclient: DownstreamClient,\n\top: string,\n\tfn: () => Promise<T>,\n\tfailOpenValue: () => T,\n): Promise<T> {\n\treturn client.callOp(op, fn, failOpenValue);\n}\n"]}

package/dist/utils/logger.d.ts

@@ -98,7 +98,9 @@ export declare function redirectLoggerToFile(filePath?: string): void;
  * output) has been configured; otherwise console.* would route back to the
  * console-backed logger output and recurse.
  */
-export declare function redirectConsoleToLogger(): void;
+export declare function redirectConsoleToLogger(options?: {
+    preserveErrorStderr?: boolean;
+}): void;
 /**
  * Redirect process.stderr writes to the structured logger.
  * Useful in TUI mode to prevent third-party libraries from corrupting the terminal.

package/dist/utils/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,UAAU;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAED,UAAU,QAAQ;IACjB,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,KAAK,CAAC,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACF;AAED;;GAEG;AACH,UAAU,YAAY;IACrB,gEAAgE;IAChE,QAAQ,EAAE,QAAQ,CAAC;IACnB,iEAAiE;IACjE,UAAU,EAAE,OAAO,CAAC;IACpB,oCAAoC;IACpC,UAAU,EAAE,OAAO,CAAC;IACpB,mDAAmD;IACnD,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;CACnC;AASD,cAAM,MAAM;IACX,OAAO,CAAC,MAAM,CAAe;gBAEjB,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC;IAS1C;;OAEG;IACH,OAAO,CAAC,SAAS;IAIjB;;OAEG;IACH,OAAO,CAAC,GAAG;IAkCX;;OAEG;IACH,OAAO,CAAC,UAAU;IAKlB;;OAEG;IACH,OAAO,CAAC,YAAY;IAsBpB;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIlD;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIjD;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIjD;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIjE;;OAEG;IACH,KAAK,CAAC,iBAAiB,EAAE,UAAU,GAAG,MAAM;IAI5C;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;CAG9C;AAkCD;;GAEG;AACH,eAAO,MAAM,MAAM,QAAe,CAAC;AAEnC;;GAEG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAkC5D;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAwB9C;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAW7C;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAsBhD"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,UAAU;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAED,UAAU,QAAQ;IACjB,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,KAAK,CAAC,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACF;AAED;;GAEG;AACH,UAAU,YAAY;IACrB,gEAAgE;IAChE,QAAQ,EAAE,QAAQ,CAAC;IACnB,iEAAiE;IACjE,UAAU,EAAE,OAAO,CAAC;IACpB,oCAAoC;IACpC,UAAU,EAAE,OAAO,CAAC;IACpB,mDAAmD;IACnD,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;CACnC;AAiBD,cAAM,MAAM;IACX,OAAO,CAAC,MAAM,CAAe;gBAEjB,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC;IAS1C;;OAEG;IACH,OAAO,CAAC,SAAS;IAIjB;;OAEG;IACH,OAAO,CAAC,GAAG;IAkCX;;OAEG;IACH,OAAO,CAAC,UAAU;IAKlB;;OAEG;IACH,OAAO,CAAC,YAAY;IAsBpB;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIlD;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIjD;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIjD;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI;IAIjE;;OAEG;IACH,KAAK,CAAC,iBAAiB,EAAE,UAAU,GAAG,MAAM;IAI5C;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;CAG9C;AAkCD;;GAEG;AACH,eAAO,MAAM,MAAM,QAAe,CAAC;AAEnC;;GAEG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAkC5D;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE;IACjD,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC9B,GAAG,IAAI,CA4BP;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAW7C;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAsBhD"}

package/dist/utils/logger.js

@@ -5,6 +5,13 @@
 import { appendFileSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { PATHS } from "../config/constants.js";
+const originalConsole = {
+    log: console.log.bind(console),
+    info: console.info.bind(console),
+    warn: console.warn.bind(console),
+    error: console.error.bind(console),
+    debug: console.debug.bind(console),
+};
 const LOG_LEVELS = {
     debug: 0,
     info: 1,
@@ -202,7 +209,7 @@ export function redirectLoggerToFile(filePath) {
  * output) has been configured; otherwise console.* would route back to the
  * console-backed logger output and recurse.
  */
-export function redirectConsoleToLogger() {
+export function redirectConsoleToLogger(options) {
     console.log = (...args) => {
         logger.info(args.map(String).join(" "));
     };
@@ -213,6 +220,10 @@ export function redirectConsoleToLogger() {
         logger.warn(args.map(String).join(" "));
     };
     console.error = (...args) => {
+        if (options?.preserveErrorStderr) {
+            originalConsole.error(...args);
+            return;
+        }
         // Preserve first Error stack if present
         const maybeError = args.find((a) => a instanceof Error);
         if (maybeError) {

package/dist/utils/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Structured logging service for Composer CLI.\n * Replaces scattered console.log/error calls with centralized, level-based logging.\n */\n\nimport { appendFileSync, mkdirSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { PATHS } from \"../config/constants.js\";\n\nexport type LogLevel = \"debug\" | \"info\" | \"warn\" | \"error\";\n\nexport interface LogContext {\n\t[key: string]: unknown;\n}\n\ninterface LogEntry {\n\tlevel: LogLevel;\n\tmessage: string;\n\ttimestamp: string;\n\tcontext?: LogContext;\n\terror?: {\n\t\tname: string;\n\t\tmessage: string;\n\t\tstack?: string;\n\t};\n}\n\n/**\n * Logger configuration\n */\ninterface LoggerConfig {\n\t/** Minimum log level to output (debug < info < warn < error) */\n\tminLevel: LogLevel;\n\t/** Whether to output JSON format (useful for log aggregation) */\n\tjsonFormat: boolean;\n\t/** Whether to include timestamps */\n\ttimestamps: boolean;\n\t/** Custom output function (defaults to console) */\n\toutput?: (entry: LogEntry) => void;\n}\n\nconst LOG_LEVELS: Record<LogLevel, number> = {\n\tdebug: 0,\n\tinfo: 1,\n\twarn: 2,\n\terror: 3,\n};\n\nclass Logger {\n\tprivate config: LoggerConfig;\n\n\tconstructor(config?: Partial<LoggerConfig>) {\n\t\tthis.config = {\n\t\t\tminLevel: (process.env.MAESTRO_LOG_LEVEL as LogLevel) ?? \"info\",\n\t\t\tjsonFormat: process.env.MAESTRO_LOG_JSON === \"1\",\n\t\t\ttimestamps: true,\n\t\t\t...config,\n\t\t};\n\t}\n\n\t/**\n\t * Check if a log level should be output\n\t */\n\tprivate shouldLog(level: LogLevel): boolean {\n\t\treturn LOG_LEVELS[level] >= LOG_LEVELS[this.config.minLevel];\n\t}\n\n\t/**\n\t * Format and output a log entry\n\t */\n\tprivate log(\n\t\tlevel: LogLevel,\n\t\tmessage: string,\n\t\tcontext?: LogContext,\n\t\terror?: Error,\n\t): void {\n\t\tif (!this.shouldLog(level)) return;\n\n\t\tconst entry: LogEntry = {\n\t\t\tlevel,\n\t\t\tmessage,\n\t\t\ttimestamp: new Date().toISOString(),\n\t\t\tcontext,\n\t\t\terror: error\n\t\t\t\t? {\n\t\t\t\t\t\tname: error.name,\n\t\t\t\t\t\tmessage: error.message,\n\t\t\t\t\t\tstack: error.stack,\n\t\t\t\t\t}\n\t\t\t\t: undefined,\n\t\t};\n\n\t\tif (this.config.output) {\n\t\t\tthis.config.output(entry);\n\t\t\treturn;\n\t\t}\n\n\t\tif (this.config.jsonFormat) {\n\t\t\tthis.outputJson(entry);\n\t\t} else {\n\t\t\tthis.outputPretty(entry);\n\t\t}\n\t}\n\n\t/**\n\t * Output as JSON (for log aggregation systems)\n\t */\n\tprivate outputJson(entry: LogEntry): void {\n\t\tconst output = entry.level === \"error\" ? console.error : console.log;\n\t\toutput(JSON.stringify(entry));\n\t}\n\n\t/**\n\t * Output as human-readable format\n\t */\n\tprivate outputPretty(entry: LogEntry): void {\n\t\tconst output = entry.level === \"error\" ? console.error : console.log;\n\t\tconst parts: string[] = [];\n\n\t\tif (this.config.timestamps) {\n\t\t\tparts.push(`[${entry.timestamp}]`);\n\t\t}\n\n\t\tparts.push(`[${entry.level.toUpperCase()}]`);\n\t\tparts.push(entry.message);\n\n\t\tif (entry.context && Object.keys(entry.context).length > 0) {\n\t\t\tparts.push(JSON.stringify(entry.context));\n\t\t}\n\n\t\toutput(parts.join(\" \"));\n\n\t\tif (entry.error?.stack) {\n\t\t\toutput(entry.error.stack);\n\t\t}\n\t}\n\n\t/**\n\t * Log debug message (verbose, typically for development)\n\t */\n\tdebug(message: string, context?: LogContext): void {\n\t\tthis.log(\"debug\", message, context);\n\t}\n\n\t/**\n\t * Log info message (general information)\n\t */\n\tinfo(message: string, context?: LogContext): void {\n\t\tthis.log(\"info\", message, context);\n\t}\n\n\t/**\n\t * Log warning message (potentially problematic situations)\n\t */\n\twarn(message: string, context?: LogContext): void {\n\t\tthis.log(\"warn\", message, context);\n\t}\n\n\t/**\n\t * Log error message (failures and exceptions)\n\t */\n\terror(message: string, error?: Error, context?: LogContext): void {\n\t\tthis.log(\"error\", message, context, error);\n\t}\n\n\t/**\n\t * Create a child logger with additional context\n\t */\n\tchild(additionalContext: LogContext): Logger {\n\t\treturn new ContextualLogger(this, additionalContext);\n\t}\n\n\t/**\n\t * Update logger configuration\n\t */\n\tconfigure(config: Partial<LoggerConfig>): void {\n\t\tthis.config = { ...this.config, ...config };\n\t}\n}\n\n/**\n * Logger that automatically includes context in all log calls\n */\nclass ContextualLogger extends Logger {\n\tconstructor(\n\t\tprivate parent: Logger,\n\t\tprivate contextData: LogContext,\n\t) {\n\t\tsuper();\n\t}\n\n\tprivate mergeContext(context?: LogContext): LogContext {\n\t\treturn { ...this.contextData, ...context };\n\t}\n\n\toverride debug(message: string, context?: LogContext): void {\n\t\tthis.parent.debug(message, this.mergeContext(context));\n\t}\n\n\toverride info(message: string, context?: LogContext): void {\n\t\tthis.parent.info(message, this.mergeContext(context));\n\t}\n\n\toverride warn(message: string, context?: LogContext): void {\n\t\tthis.parent.warn(message, this.mergeContext(context));\n\t}\n\n\toverride error(message: string, error?: Error, context?: LogContext): void {\n\t\tthis.parent.error(message, error, this.mergeContext(context));\n\t}\n}\n\n/**\n * Global logger instance\n */\nexport const logger = new Logger();\n\n/**\n * Create a logger for a specific module/component\n */\nexport function createLogger(moduleName: string): Logger {\n\treturn logger.child({ module: moduleName });\n}\n\n/**\n * Silence the logger (useful for TUI mode where stdout must not be polluted)\n */\nexport function silenceLogger(): void {\n\tlogger.configure({ output: () => {} });\n}\n\n/**\n * Redirect all logs to a file (useful for TUI mode)\n * @param filePath - Path to the log file (defaults to ~/.maestro/logs/maestro.log)\n */\nexport function redirectLoggerToFile(filePath?: string): void {\n\tconst logFile = filePath ?? join(PATHS.MAESTRO_HOME, \"logs\", \"maestro.log\");\n\n\t// Ensure directory exists\n\ttry {\n\t\tmkdirSync(dirname(logFile), { recursive: true });\n\t} catch {\n\t\t// Directory may already exist\n\t}\n\n\tlogger.configure({\n\t\toutput: (entry) => {\n\t\t\tconst parts: string[] = [];\n\t\t\tparts.push(`[${entry.timestamp}]`);\n\t\t\tparts.push(`[${entry.level.toUpperCase()}]`);\n\t\t\tparts.push(entry.message);\n\n\t\t\tif (entry.context && Object.keys(entry.context).length > 0) {\n\t\t\t\tparts.push(JSON.stringify(entry.context));\n\t\t\t}\n\n\t\t\tlet line = `${parts.join(\" \")}\\n`;\n\n\t\t\tif (entry.error?.stack) {\n\t\t\t\tline += `${entry.error.stack}\\n`;\n\t\t\t}\n\n\t\t\ttry {\n\t\t\t\tappendFileSync(logFile, line);\n\t\t\t} catch {\n\t\t\t\t// Silently fail if we can't write to the log file\n\t\t\t}\n\t\t},\n\t});\n}\n\n/**\n * Redirect global console methods to the structured logger.\n *\n * Important: Call this only after redirectLoggerToFile() (or a custom logger\n * output) has been configured; otherwise console.* would route back to the\n * console-backed logger output and recurse.\n */\nexport function redirectConsoleToLogger(): void {\n\tconsole.log = (...args: unknown[]) => {\n\t\tlogger.info(args.map(String).join(\" \"));\n\t};\n\tconsole.info = (...args: unknown[]) => {\n\t\tlogger.info(args.map(String).join(\" \"));\n\t};\n\tconsole.warn = (...args: unknown[]) => {\n\t\tlogger.warn(args.map(String).join(\" \"));\n\t};\n\tconsole.error = (...args: unknown[]) => {\n\t\t// Preserve first Error stack if present\n\t\tconst maybeError = args.find((a) => a instanceof Error) as\n\t\t\t| Error\n\t\t\t| undefined;\n\t\tif (maybeError) {\n\t\t\tlogger.error(maybeError.message, maybeError);\n\t\t} else {\n\t\t\tlogger.error(args.map(String).join(\" \"));\n\t\t}\n\t};\n\tconsole.debug = (...args: unknown[]) => {\n\t\tlogger.debug(args.map(String).join(\" \"));\n\t};\n}\n\n/**\n * Redirect process.stderr writes to the structured logger.\n * Useful in TUI mode to prevent third-party libraries from corrupting the terminal.\n */\nexport function redirectStderrToLogger(): void {\n\tprocess.stderr.write = (chunk: unknown) => {\n\t\tconst text =\n\t\t\ttypeof chunk === \"string\"\n\t\t\t\t? chunk\n\t\t\t\t: chunk instanceof Buffer\n\t\t\t\t\t? chunk.toString()\n\t\t\t\t\t: String(chunk);\n\t\tlogger.error(text.trimEnd());\n\t\treturn true;\n\t};\n}\n\n/**\n * Wire process warning / rejection hooks into the logger so they don't hit stderr.\n */\nexport function pipeProcessEventsToLogger(): void {\n\tprocess.on(\"warning\", (warning) => {\n\t\tlogger.warn(\n\t\t\t`${warning.name}: ${warning.message}${\n\t\t\t\twarning.stack ? `\\n${warning.stack}` : \"\"\n\t\t\t}`,\n\t\t);\n\t});\n\n\tprocess.on(\"unhandledRejection\", (reason, promise) => {\n\t\tlogger.error(\n\t\t\t`UnhandledRejection: ${String(reason)} (promise: ${String(promise)})`,\n\t\t);\n\t});\n\n\tprocess.on(\"uncaughtException\", (error) => {\n\t\tif (error instanceof Error) {\n\t\t\tlogger.error(error.message, error);\n\t\t} else {\n\t\t\tlogger.error(`UncaughtException: ${String(error)}`);\n\t\t}\n\t});\n}\n"]}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Structured logging service for Composer CLI.\n * Replaces scattered console.log/error calls with centralized, level-based logging.\n */\n\nimport { appendFileSync, mkdirSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { PATHS } from \"../config/constants.js\";\n\nexport type LogLevel = \"debug\" | \"info\" | \"warn\" | \"error\";\n\nexport interface LogContext {\n\t[key: string]: unknown;\n}\n\ninterface LogEntry {\n\tlevel: LogLevel;\n\tmessage: string;\n\ttimestamp: string;\n\tcontext?: LogContext;\n\terror?: {\n\t\tname: string;\n\t\tmessage: string;\n\t\tstack?: string;\n\t};\n}\n\n/**\n * Logger configuration\n */\ninterface LoggerConfig {\n\t/** Minimum log level to output (debug < info < warn < error) */\n\tminLevel: LogLevel;\n\t/** Whether to output JSON format (useful for log aggregation) */\n\tjsonFormat: boolean;\n\t/** Whether to include timestamps */\n\ttimestamps: boolean;\n\t/** Custom output function (defaults to console) */\n\toutput?: (entry: LogEntry) => void;\n}\n\nconst originalConsole = {\n\tlog: console.log.bind(console),\n\tinfo: console.info.bind(console),\n\twarn: console.warn.bind(console),\n\terror: console.error.bind(console),\n\tdebug: console.debug.bind(console),\n};\n\nconst LOG_LEVELS: Record<LogLevel, number> = {\n\tdebug: 0,\n\tinfo: 1,\n\twarn: 2,\n\terror: 3,\n};\n\nclass Logger {\n\tprivate config: LoggerConfig;\n\n\tconstructor(config?: Partial<LoggerConfig>) {\n\t\tthis.config = {\n\t\t\tminLevel: (process.env.MAESTRO_LOG_LEVEL as LogLevel) ?? \"info\",\n\t\t\tjsonFormat: process.env.MAESTRO_LOG_JSON === \"1\",\n\t\t\ttimestamps: true,\n\t\t\t...config,\n\t\t};\n\t}\n\n\t/**\n\t * Check if a log level should be output\n\t */\n\tprivate shouldLog(level: LogLevel): boolean {\n\t\treturn LOG_LEVELS[level] >= LOG_LEVELS[this.config.minLevel];\n\t}\n\n\t/**\n\t * Format and output a log entry\n\t */\n\tprivate log(\n\t\tlevel: LogLevel,\n\t\tmessage: string,\n\t\tcontext?: LogContext,\n\t\terror?: Error,\n\t): void {\n\t\tif (!this.shouldLog(level)) return;\n\n\t\tconst entry: LogEntry = {\n\t\t\tlevel,\n\t\t\tmessage,\n\t\t\ttimestamp: new Date().toISOString(),\n\t\t\tcontext,\n\t\t\terror: error\n\t\t\t\t? {\n\t\t\t\t\t\tname: error.name,\n\t\t\t\t\t\tmessage: error.message,\n\t\t\t\t\t\tstack: error.stack,\n\t\t\t\t\t}\n\t\t\t\t: undefined,\n\t\t};\n\n\t\tif (this.config.output) {\n\t\t\tthis.config.output(entry);\n\t\t\treturn;\n\t\t}\n\n\t\tif (this.config.jsonFormat) {\n\t\t\tthis.outputJson(entry);\n\t\t} else {\n\t\t\tthis.outputPretty(entry);\n\t\t}\n\t}\n\n\t/**\n\t * Output as JSON (for log aggregation systems)\n\t */\n\tprivate outputJson(entry: LogEntry): void {\n\t\tconst output = entry.level === \"error\" ? console.error : console.log;\n\t\toutput(JSON.stringify(entry));\n\t}\n\n\t/**\n\t * Output as human-readable format\n\t */\n\tprivate outputPretty(entry: LogEntry): void {\n\t\tconst output = entry.level === \"error\" ? console.error : console.log;\n\t\tconst parts: string[] = [];\n\n\t\tif (this.config.timestamps) {\n\t\t\tparts.push(`[${entry.timestamp}]`);\n\t\t}\n\n\t\tparts.push(`[${entry.level.toUpperCase()}]`);\n\t\tparts.push(entry.message);\n\n\t\tif (entry.context && Object.keys(entry.context).length > 0) {\n\t\t\tparts.push(JSON.stringify(entry.context));\n\t\t}\n\n\t\toutput(parts.join(\" \"));\n\n\t\tif (entry.error?.stack) {\n\t\t\toutput(entry.error.stack);\n\t\t}\n\t}\n\n\t/**\n\t * Log debug message (verbose, typically for development)\n\t */\n\tdebug(message: string, context?: LogContext): void {\n\t\tthis.log(\"debug\", message, context);\n\t}\n\n\t/**\n\t * Log info message (general information)\n\t */\n\tinfo(message: string, context?: LogContext): void {\n\t\tthis.log(\"info\", message, context);\n\t}\n\n\t/**\n\t * Log warning message (potentially problematic situations)\n\t */\n\twarn(message: string, context?: LogContext): void {\n\t\tthis.log(\"warn\", message, context);\n\t}\n\n\t/**\n\t * Log error message (failures and exceptions)\n\t */\n\terror(message: string, error?: Error, context?: LogContext): void {\n\t\tthis.log(\"error\", message, context, error);\n\t}\n\n\t/**\n\t * Create a child logger with additional context\n\t */\n\tchild(additionalContext: LogContext): Logger {\n\t\treturn new ContextualLogger(this, additionalContext);\n\t}\n\n\t/**\n\t * Update logger configuration\n\t */\n\tconfigure(config: Partial<LoggerConfig>): void {\n\t\tthis.config = { ...this.config, ...config };\n\t}\n}\n\n/**\n * Logger that automatically includes context in all log calls\n */\nclass ContextualLogger extends Logger {\n\tconstructor(\n\t\tprivate parent: Logger,\n\t\tprivate contextData: LogContext,\n\t) {\n\t\tsuper();\n\t}\n\n\tprivate mergeContext(context?: LogContext): LogContext {\n\t\treturn { ...this.contextData, ...context };\n\t}\n\n\toverride debug(message: string, context?: LogContext): void {\n\t\tthis.parent.debug(message, this.mergeContext(context));\n\t}\n\n\toverride info(message: string, context?: LogContext): void {\n\t\tthis.parent.info(message, this.mergeContext(context));\n\t}\n\n\toverride warn(message: string, context?: LogContext): void {\n\t\tthis.parent.warn(message, this.mergeContext(context));\n\t}\n\n\toverride error(message: string, error?: Error, context?: LogContext): void {\n\t\tthis.parent.error(message, error, this.mergeContext(context));\n\t}\n}\n\n/**\n * Global logger instance\n */\nexport const logger = new Logger();\n\n/**\n * Create a logger for a specific module/component\n */\nexport function createLogger(moduleName: string): Logger {\n\treturn logger.child({ module: moduleName });\n}\n\n/**\n * Silence the logger (useful for TUI mode where stdout must not be polluted)\n */\nexport function silenceLogger(): void {\n\tlogger.configure({ output: () => {} });\n}\n\n/**\n * Redirect all logs to a file (useful for TUI mode)\n * @param filePath - Path to the log file (defaults to ~/.maestro/logs/maestro.log)\n */\nexport function redirectLoggerToFile(filePath?: string): void {\n\tconst logFile = filePath ?? join(PATHS.MAESTRO_HOME, \"logs\", \"maestro.log\");\n\n\t// Ensure directory exists\n\ttry {\n\t\tmkdirSync(dirname(logFile), { recursive: true });\n\t} catch {\n\t\t// Directory may already exist\n\t}\n\n\tlogger.configure({\n\t\toutput: (entry) => {\n\t\t\tconst parts: string[] = [];\n\t\t\tparts.push(`[${entry.timestamp}]`);\n\t\t\tparts.push(`[${entry.level.toUpperCase()}]`);\n\t\t\tparts.push(entry.message);\n\n\t\t\tif (entry.context && Object.keys(entry.context).length > 0) {\n\t\t\t\tparts.push(JSON.stringify(entry.context));\n\t\t\t}\n\n\t\t\tlet line = `${parts.join(\" \")}\\n`;\n\n\t\t\tif (entry.error?.stack) {\n\t\t\t\tline += `${entry.error.stack}\\n`;\n\t\t\t}\n\n\t\t\ttry {\n\t\t\t\tappendFileSync(logFile, line);\n\t\t\t} catch {\n\t\t\t\t// Silently fail if we can't write to the log file\n\t\t\t}\n\t\t},\n\t});\n}\n\n/**\n * Redirect global console methods to the structured logger.\n *\n * Important: Call this only after redirectLoggerToFile() (or a custom logger\n * output) has been configured; otherwise console.* would route back to the\n * console-backed logger output and recurse.\n */\nexport function redirectConsoleToLogger(options?: {\n\tpreserveErrorStderr?: boolean;\n}): void {\n\tconsole.log = (...args: unknown[]) => {\n\t\tlogger.info(args.map(String).join(\" \"));\n\t};\n\tconsole.info = (...args: unknown[]) => {\n\t\tlogger.info(args.map(String).join(\" \"));\n\t};\n\tconsole.warn = (...args: unknown[]) => {\n\t\tlogger.warn(args.map(String).join(\" \"));\n\t};\n\tconsole.error = (...args: unknown[]) => {\n\t\tif (options?.preserveErrorStderr) {\n\t\t\toriginalConsole.error(...args);\n\t\t\treturn;\n\t\t}\n\t\t// Preserve first Error stack if present\n\t\tconst maybeError = args.find((a) => a instanceof Error) as\n\t\t\t| Error\n\t\t\t| undefined;\n\t\tif (maybeError) {\n\t\t\tlogger.error(maybeError.message, maybeError);\n\t\t} else {\n\t\t\tlogger.error(args.map(String).join(\" \"));\n\t\t}\n\t};\n\tconsole.debug = (...args: unknown[]) => {\n\t\tlogger.debug(args.map(String).join(\" \"));\n\t};\n}\n\n/**\n * Redirect process.stderr writes to the structured logger.\n * Useful in TUI mode to prevent third-party libraries from corrupting the terminal.\n */\nexport function redirectStderrToLogger(): void {\n\tprocess.stderr.write = (chunk: unknown) => {\n\t\tconst text =\n\t\t\ttypeof chunk === \"string\"\n\t\t\t\t? chunk\n\t\t\t\t: chunk instanceof Buffer\n\t\t\t\t\t? chunk.toString()\n\t\t\t\t\t: String(chunk);\n\t\tlogger.error(text.trimEnd());\n\t\treturn true;\n\t};\n}\n\n/**\n * Wire process warning / rejection hooks into the logger so they don't hit stderr.\n */\nexport function pipeProcessEventsToLogger(): void {\n\tprocess.on(\"warning\", (warning) => {\n\t\tlogger.warn(\n\t\t\t`${warning.name}: ${warning.message}${\n\t\t\t\twarning.stack ? `\\n${warning.stack}` : \"\"\n\t\t\t}`,\n\t\t);\n\t});\n\n\tprocess.on(\"unhandledRejection\", (reason, promise) => {\n\t\tlogger.error(\n\t\t\t`UnhandledRejection: ${String(reason)} (promise: ${String(promise)})`,\n\t\t);\n\t});\n\n\tprocess.on(\"uncaughtException\", (error) => {\n\t\tif (error instanceof Error) {\n\t\t\tlogger.error(error.message, error);\n\t\t} else {\n\t\t\tlogger.error(`UncaughtException: ${String(error)}`);\n\t\t}\n\t});\n}\n"]}

package/dist/utils/oauth-http.d.ts

@@ -0,0 +1,8 @@
+interface OAuthHttpOptions {
+    maxAttempts?: number;
+    serviceName: string;
+    timeoutMs?: number;
+}
+export declare function fetchOAuthHttp(input: Parameters<typeof fetch>[0], init: RequestInit, options: OAuthHttpOptions): Promise<Response>;
+export {};
+//# sourceMappingURL=oauth-http.d.ts.map

package/dist/utils/oauth-http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-http.d.ts","sourceRoot":"","sources":["../../src/utils/oauth-http.ts"],"names":[],"mappings":"AAaA,UAAU,gBAAgB;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AA2BD,wBAAgB,cAAc,CAC7B,KAAK,EAAE,UAAU,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,EAClC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,gBAAgB,GACvB,OAAO,CAAC,QAAQ,CAAC,CASnB"}

package/dist/utils/oauth-http.js

@@ -0,0 +1,41 @@
+import { fetchDownstream } from "./downstream-http.js";
+const DEFAULT_OAUTH_HTTP_MAX_ATTEMPTS = 1;
+const DEFAULT_OAUTH_HTTP_TIMEOUT_MS = 10_000;
+const MAX_ATTEMPTS_ENV_VARS = [
+    "MAESTRO_OAUTH_HTTP_MAX_ATTEMPTS",
+    "OAUTH_HTTP_MAX_ATTEMPTS",
+];
+const TIMEOUT_ENV_VARS = [
+    "MAESTRO_OAUTH_HTTP_TIMEOUT_MS",
+    "OAUTH_HTTP_TIMEOUT_MS",
+];
+function getEnvPositiveInt(names, fallback) {
+    for (const name of names) {
+        const value = process.env[name]?.trim();
+        if (!value) {
+            continue;
+        }
+        const parsed = Number.parseInt(value, 10);
+        if (Number.isFinite(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    return fallback;
+}
+function getOAuthHttpMaxAttempts() {
+    return getEnvPositiveInt(MAX_ATTEMPTS_ENV_VARS, DEFAULT_OAUTH_HTTP_MAX_ATTEMPTS);
+}
+function getOAuthHttpTimeoutMs() {
+    return getEnvPositiveInt(TIMEOUT_ENV_VARS, DEFAULT_OAUTH_HTTP_TIMEOUT_MS);
+}
+export function fetchOAuthHttp(input, init, options) {
+    return fetchDownstream(input, init, {
+        serviceName: options.serviceName,
+        failureMode: "required",
+        timeoutMs: options.timeoutMs ?? getOAuthHttpTimeoutMs(),
+        maxAttempts: options.maxAttempts ?? getOAuthHttpMaxAttempts(),
+        initialDelayMs: 100,
+        maxDelayMs: 1_000,
+    });
+}
+//# sourceMappingURL=oauth-http.js.map

package/dist/utils/oauth-http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-http.js","sourceRoot":"","sources":["../../src/utils/oauth-http.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,MAAM,+BAA+B,GAAG,CAAC,CAAC;AAC1C,MAAM,6BAA6B,GAAG,MAAM,CAAC;AAC7C,MAAM,qBAAqB,GAAG;IAC7B,iCAAiC;IACjC,yBAAyB;CAChB,CAAC;AACX,MAAM,gBAAgB,GAAG;IACxB,+BAA+B;IAC/B,uBAAuB;CACd,CAAC;AAQX,SAAS,iBAAiB,CAAC,KAAwB,EAAE,QAAgB;IACpE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC;QACxC,IAAI,CAAC,KAAK,EAAE,CAAC;YACZ,SAAS;QACV,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC1C,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3C,OAAO,MAAM,CAAC;QACf,CAAC;IACF,CAAC;IACD,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED,SAAS,uBAAuB;IAC/B,OAAO,iBAAiB,CACvB,qBAAqB,EACrB,+BAA+B,CAC/B,CAAC;AACH,CAAC;AAED,SAAS,qBAAqB;IAC7B,OAAO,iBAAiB,CAAC,gBAAgB,EAAE,6BAA6B,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,cAAc,CAC7B,KAAkC,EAClC,IAAiB,EACjB,OAAyB;IAEzB,OAAO,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE;QACnC,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,WAAW,EAAE,UAAU;QACvB,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,qBAAqB,EAAE;QACvD,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,uBAAuB,EAAE;QAC7D,cAAc,EAAE,GAAG;QACnB,UAAU,EAAE,KAAK;KACjB,CAAC,CAAC;AACJ,CAAC","sourcesContent":["import { fetchDownstream } from \"./downstream-http.js\";\n\nconst DEFAULT_OAUTH_HTTP_MAX_ATTEMPTS = 1;\nconst DEFAULT_OAUTH_HTTP_TIMEOUT_MS = 10_000;\nconst MAX_ATTEMPTS_ENV_VARS = [\n\t\"MAESTRO_OAUTH_HTTP_MAX_ATTEMPTS\",\n\t\"OAUTH_HTTP_MAX_ATTEMPTS\",\n] as const;\nconst TIMEOUT_ENV_VARS = [\n\t\"MAESTRO_OAUTH_HTTP_TIMEOUT_MS\",\n\t\"OAUTH_HTTP_TIMEOUT_MS\",\n] as const;\n\ninterface OAuthHttpOptions {\n\tmaxAttempts?: number;\n\tserviceName: string;\n\ttimeoutMs?: number;\n}\n\nfunction getEnvPositiveInt(names: readonly string[], fallback: number): number {\n\tfor (const name of names) {\n\t\tconst value = process.env[name]?.trim();\n\t\tif (!value) {\n\t\t\tcontinue;\n\t\t}\n\t\tconst parsed = Number.parseInt(value, 10);\n\t\tif (Number.isFinite(parsed) && parsed > 0) {\n\t\t\treturn parsed;\n\t\t}\n\t}\n\treturn fallback;\n}\n\nfunction getOAuthHttpMaxAttempts(): number {\n\treturn getEnvPositiveInt(\n\t\tMAX_ATTEMPTS_ENV_VARS,\n\t\tDEFAULT_OAUTH_HTTP_MAX_ATTEMPTS,\n\t);\n}\n\nfunction getOAuthHttpTimeoutMs(): number {\n\treturn getEnvPositiveInt(TIMEOUT_ENV_VARS, DEFAULT_OAUTH_HTTP_TIMEOUT_MS);\n}\n\nexport function fetchOAuthHttp(\n\tinput: Parameters<typeof fetch>[0],\n\tinit: RequestInit,\n\toptions: OAuthHttpOptions,\n): Promise<Response> {\n\treturn fetchDownstream(input, init, {\n\t\tserviceName: options.serviceName,\n\t\tfailureMode: \"required\",\n\t\ttimeoutMs: options.timeoutMs ?? getOAuthHttpTimeoutMs(),\n\t\tmaxAttempts: options.maxAttempts ?? getOAuthHttpMaxAttempts(),\n\t\tinitialDelayMs: 100,\n\t\tmaxDelayMs: 1_000,\n\t});\n}\n"]}

package/dist/utils/path-utils.d.ts

@@ -0,0 +1,2 @@
+export declare function uniquePaths(paths: ReadonlyArray<string | null | undefined>): string[];
+//# sourceMappingURL=path-utils.d.ts.map

package/dist/utils/path-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../../src/utils/path-utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAC1B,KAAK,EAAE,aAAa,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,GAC7C,MAAM,EAAE,CASV"}

package/dist/utils/path-utils.js

@@ -0,0 +1,12 @@
+export function uniquePaths(paths) {
+    const seen = new Set();
+    const result = [];
+    for (const path of paths) {
+        if (!path || seen.has(path))
+            continue;
+        seen.add(path);
+        result.push(path);
+    }
+    return result;
+}
+//# sourceMappingURL=path-utils.js.map

package/dist/utils/path-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-utils.js","sourceRoot":"","sources":["../../src/utils/path-utils.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,WAAW,CAC1B,KAA+C;IAE/C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QACtC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACf,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC","sourcesContent":["export function uniquePaths(\n\tpaths: ReadonlyArray<string | null | undefined>,\n): string[] {\n\tconst seen = new Set<string>();\n\tconst result: string[] = [];\n\tfor (const path of paths) {\n\t\tif (!path || seen.has(path)) continue;\n\t\tseen.add(path);\n\t\tresult.push(path);\n\t}\n\treturn result;\n}\n"]}

package/dist/utils/path-validation.d.ts

@@ -52,7 +52,7 @@ export declare function validatePathSync(path: string, baseDir?: string): string
 /**
  * Check if a path is within the current working directory
  */
-export declare function isWithinCwd(path: string): boolean;
+export declare function isWithinCwd(path: string, cwd?: string): boolean;
 /**
  * Safely join paths with validation
  */

package/dist/utils/path-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path-validation.d.ts","sourceRoot":"","sources":["../../src/utils/path-validation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAG5B,IAAI,EAAE,MAAM;aACZ,MAAM,EAAE,MAAM;gBAF9B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM;CAK/B;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMlD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAevE;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,gCAAgC;IAChC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,sCAAsC;IACtC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,sCAAsC;IACtC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAChC,wBAAwB;IACxB,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,wBAAsB,YAAY,CACjC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,qBAA0B,GACjC,OAAO,CAAC,MAAM,CAAC,CA8HjB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAYvE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CASjD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAiBjE;AAED;;GAEG;AACH,wBAAsB,aAAa,CAClC,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,GAAE,qBAA0B,GACjC,OAAO,CAAC,MAAM,EAAE,CAAC,CAEnB"}
+{"version":3,"file":"path-validation.d.ts","sourceRoot":"","sources":["../../src/utils/path-validation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAG5B,IAAI,EAAE,MAAM;aACZ,MAAM,EAAE,MAAM;gBAF9B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM;CAK/B;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMlD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAevE;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,gCAAgC;IAChC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,sCAAsC;IACtC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,sCAAsC;IACtC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAChC,wBAAwB;IACxB,UAAU,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,wBAAsB,YAAY,CACjC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,qBAA0B,GACjC,OAAO,CAAC,MAAM,CAAC,CA8HjB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAYvE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAgB,GAAG,OAAO,CAStE;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAiBjE;AAED;;GAEG;AACH,wBAAsB,aAAa,CAClC,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,GAAE,qBAA0B,GACjC,OAAO,CAAC,MAAM,EAAE,CAAC,CAEnB"}

package/dist/utils/path-validation.js

@@ -153,12 +153,12 @@ export function validatePathSync(path, baseDir) {
 /**
  * Check if a path is within the current working directory
  */
-export function isWithinCwd(path) {
+export function isWithinCwd(path, cwd = process.cwd()) {
     const normalizedPath = normalizePath(path);
-    const cwd = process.cwd();
+    const normalizedCwd = normalizePath(cwd);
     const isWindows = process.platform === "win32";
     const pathCheck = isWindows ? normalizedPath.toLowerCase() : normalizedPath;
-    const cwdCheck = isWindows ? cwd.toLowerCase() : cwd;
+    const cwdCheck = isWindows ? normalizedCwd.toLowerCase() : normalizedCwd;
     return pathCheck.startsWith(cwdCheck + sep) || pathCheck === cwdCheck;
 }
 /**

package/dist/utils/path-validation.js.map

@@ -1 +1 @@
-{"version":3,"file":"path-validation.js","sourceRoot":"","sources":["../../src/utils/path-validation.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Path validation utilities for secure file operations.\n * Prevents path traversal attacks and validates file paths.\n */\n\nimport { constants } from \"node:fs\";\nimport { access, realpath, stat } from \"node:fs/promises\";\nimport { basename, isAbsolute, normalize, resolve, sep } from \"node:path\";\nimport { ERRORS, LIMITS } from \"../config/constants.js\";\nimport { createLogger } from \"./logger.js\";\nimport { expandTildePathWithHomeDir, getHomeDir } from \"./path-expansion.js\";\n\nconst logger = createLogger(\"path-validation\");\n\n/**\n * Error thrown when path validation fails\n */\nexport class PathValidationError extends Error {\n\tconstructor(\n\t\tmessage: string,\n\t\tpublic readonly path: string,\n\t\tpublic readonly reason: string,\n\t) {\n\t\tsuper(message);\n\t\tthis.name = \"PathValidationError\";\n\t}\n}\n\n/**\n * Expand ~ to home directory\n */\nexport function expandUserPath(path: string): string {\n\treturn expandTildePathWithHomeDir(path, getHomeDir());\n}\n\n/**\n * Normalize and resolve path to absolute form\n */\nexport function normalizePath(path: string): string {\n\tconst expanded = expandUserPath(path);\n\tconst normalized = normalize(expanded);\n\treturn isAbsolute(normalized)\n\t\t? normalized\n\t\t: resolve(process.cwd(), normalized);\n}\n\n/**\n * Check if path attempts to escape a base directory\n */\nexport function isPathTraversal(path: string, baseDir?: string): boolean {\n\tconst normalizedPath = normalizePath(path);\n\tconst base = baseDir ? normalizePath(baseDir) : process.cwd();\n\n\t// Check if the normalized path starts with the base directory\n\tconst isWindows = process.platform === \"win32\";\n\tconst normalizedPathCheck = isWindows\n\t\t? normalizedPath.toLowerCase()\n\t\t: normalizedPath;\n\tconst baseCheck = isWindows ? base.toLowerCase() : base;\n\n\treturn (\n\t\t!normalizedPathCheck.startsWith(baseCheck + sep) &&\n\t\tnormalizedPathCheck !== baseCheck\n\t);\n}\n\n/**\n * Validate that a path is safe and accessible\n */\nexport interface PathValidationOptions {\n\t/** Require the path to exist */\n\tmustExist?: boolean;\n\t/** Require the path to be readable */\n\tmustBeReadable?: boolean;\n\t/** Require the path to be writable */\n\tmustBeWritable?: boolean;\n\t/** Base directory to restrict access to */\n\tbaseDir?: string;\n\t/** Maximum file size in bytes */\n\tmaxSize?: number;\n\t/** Allowed file extensions */\n\tallowedExtensions?: Set<string>;\n\t/** Disallow symlinks */\n\tnoSymlinks?: boolean;\n}\n\n/**\n * Comprehensive path validation\n */\nexport async function validatePath(\n\tpath: string,\n\toptions: PathValidationOptions = {},\n): Promise<string> {\n\tconst {\n\t\tmustExist = false,\n\t\tmustBeReadable = false,\n\t\tmustBeWritable = false,\n\t\tbaseDir,\n\t\tmaxSize,\n\t\tallowedExtensions,\n\t\tnoSymlinks = false,\n\t} = options;\n\n\t// Normalize the path\n\tlet normalizedPath: string;\n\ttry {\n\t\tnormalizedPath = normalizePath(path);\n\t} catch (error) {\n\t\tlogger.warn(\"Path normalization failed\", { path, error });\n\t\tthrow new PathValidationError(\n\t\t\t`Invalid path: ${path}`,\n\t\t\tpath,\n\t\t\t\"normalization_failed\",\n\t\t);\n\t}\n\n\t// Check for path traversal\n\tif (baseDir && isPathTraversal(normalizedPath, baseDir)) {\n\t\tlogger.warn(\"Path traversal attempt detected\", {\n\t\t\tpath,\n\t\t\tnormalizedPath,\n\t\t\tbaseDir,\n\t\t});\n\t\tthrow new PathValidationError(\n\t\t\t`Path traversal detected: ${path}`,\n\t\t\tpath,\n\t\t\t\"path_traversal\",\n\t\t);\n\t}\n\n\t// Check existence if required\n\tif (mustExist || mustBeReadable || mustBeWritable || maxSize !== undefined) {\n\t\ttry {\n\t\t\tawait access(normalizedPath, constants.F_OK);\n\t\t} catch {\n\t\t\tthrow new PathValidationError(\n\t\t\t\t`File not found: ${path}`,\n\t\t\t\tnormalizedPath,\n\t\t\t\t\"not_found\",\n\t\t\t);\n\t\t}\n\t}\n\n\t// Check readability\n\tif (mustBeReadable) {\n\t\ttry {\n\t\t\tawait access(normalizedPath, constants.R_OK);\n\t\t} catch {\n\t\t\tthrow new PathValidationError(\n\t\t\t\t`File not readable: ${path}`,\n\t\t\t\tnormalizedPath,\n\t\t\t\t\"not_readable\",\n\t\t\t);\n\t\t}\n\t}\n\n\t// Check writability\n\tif (mustBeWritable) {\n\t\ttry {\n\t\t\tawait access(normalizedPath, constants.W_OK);\n\t\t} catch {\n\t\t\tthrow new PathValidationError(\n\t\t\t\t`File not writable: ${path}`,\n\t\t\t\tnormalizedPath,\n\t\t\t\t\"not_writable\",\n\t\t\t);\n\t\t}\n\t}\n\n\t// Check file size\n\tif (maxSize !== undefined) {\n\t\ttry {\n\t\t\tconst stats = await stat(normalizedPath);\n\t\t\tif (stats.size > maxSize) {\n\t\t\t\tthrow new PathValidationError(\n\t\t\t\t\t`${ERRORS.FILE_TOO_LARGE}: ${path} (${stats.size} bytes, max: ${maxSize} bytes)`,\n\t\t\t\t\tnormalizedPath,\n\t\t\t\t\t\"file_too_large\",\n\t\t\t\t);\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tif (error instanceof PathValidationError) throw error;\n\t\t\t// Ignore stat errors if file doesn't exist\n\t\t}\n\t}\n\n\t// Check file extension from the last path segment (so dirs like .git don't affect it)\n\tif (allowedExtensions && allowedExtensions.size > 0) {\n\t\tconst name = basename(normalizedPath);\n\t\tconst lastDot = name.lastIndexOf(\".\");\n\t\tconst ext = lastDot >= 0 ? name.slice(lastDot) : \"\";\n\t\tif (!allowedExtensions.has(ext)) {\n\t\t\tthrow new PathValidationError(\n\t\t\t\t`File extension not allowed: ${ext || \"(none)\"}`,\n\t\t\t\tnormalizedPath,\n\t\t\t\t\"extension_not_allowed\",\n\t\t\t);\n\t\t}\n\t}\n\n\t// Check for symlinks\n\tif (noSymlinks) {\n\t\ttry {\n\t\t\tconst realPath = await realpath(normalizedPath);\n\t\t\tif (realPath !== normalizedPath) {\n\t\t\t\tthrow new PathValidationError(\n\t\t\t\t\t`Symlinks not allowed: ${path}`,\n\t\t\t\t\tnormalizedPath,\n\t\t\t\t\t\"symlink_detected\",\n\t\t\t\t);\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tif (error instanceof PathValidationError) throw error;\n\t\t\t// Ignore errors if file doesn't exist yet\n\t\t}\n\t}\n\n\treturn normalizedPath;\n}\n\n/**\n * Synchronous path validation (basic checks only)\n */\nexport function validatePathSync(path: string, baseDir?: string): string {\n\tconst normalizedPath = normalizePath(path);\n\n\tif (baseDir && isPathTraversal(normalizedPath, baseDir)) {\n\t\tthrow new PathValidationError(\n\t\t\t`Path traversal detected: ${path}`,\n\t\t\tpath,\n\t\t\t\"path_traversal\",\n\t\t);\n\t}\n\n\treturn normalizedPath;\n}\n\n/**\n * Check if a path is within the current working directory\n */\nexport function isWithinCwd(path: string): boolean {\n\tconst normalizedPath = normalizePath(path);\n\tconst cwd = process.cwd();\n\tconst isWindows = process.platform === \"win32\";\n\n\tconst pathCheck = isWindows ? normalizedPath.toLowerCase() : normalizedPath;\n\tconst cwdCheck = isWindows ? cwd.toLowerCase() : cwd;\n\n\treturn pathCheck.startsWith(cwdCheck + sep) || pathCheck === cwdCheck;\n}\n\n/**\n * Safely join paths with validation\n */\nexport function safejoin(base: string, ...parts: string[]): string {\n\tconst joined = resolve(base, ...parts);\n\tconst normalizedBase = normalizePath(base);\n\n\tconst isWindows = process.platform === \"win32\";\n\tconst joinedCheck = isWindows ? joined.toLowerCase() : joined;\n\tconst baseCheck = isWindows ? normalizedBase.toLowerCase() : normalizedBase;\n\n\tif (!joinedCheck.startsWith(baseCheck + sep) && joinedCheck !== baseCheck) {\n\t\tthrow new PathValidationError(\n\t\t\t`Path would escape base directory: ${parts.join(\"/\")}`,\n\t\t\tjoined,\n\t\t\t\"path_traversal\",\n\t\t);\n\t}\n\n\treturn joined;\n}\n\n/**\n * Validate multiple paths in parallel\n */\nexport async function validatePaths(\n\tpaths: string[],\n\toptions: PathValidationOptions = {},\n): Promise<string[]> {\n\treturn Promise.all(paths.map((path) => validatePath(path, options)));\n}\n"]}
+{"version":3,"file":"path-validation.js","sourceRoot":"","sources":["../../src/utils/path-validation.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Path validation utilities for secure file operations.\n * Prevents path traversal attacks and validates file paths.\n */\n\nimport { constants } from \"node:fs\";\nimport { access, realpath, stat } from \"node:fs/promises\";\nimport { basename, isAbsolute, normalize, resolve, sep } from \"node:path\";\nimport { ERRORS, LIMITS } from \"../config/constants.js\";\nimport { createLogger } from \"./logger.js\";\nimport { expandTildePathWithHomeDir, getHomeDir } from \"./path-expansion.js\";\n\nconst logger = createLogger(\"path-validation\");\n\n/**\n * Error thrown when path validation fails\n */\nexport class PathValidationError extends Error {\n\tconstructor(\n\t\tmessage: string,\n\t\tpublic readonly path: string,\n\t\tpublic readonly reason: string,\n\t) {\n\t\tsuper(message);\n\t\tthis.name = \"PathValidationError\";\n\t}\n}\n\n/**\n * Expand ~ to home directory\n */\nexport function expandUserPath(path: string): string {\n\treturn expandTildePathWithHomeDir(path, getHomeDir());\n}\n\n/**\n * Normalize and resolve path to absolute form\n */\nexport function normalizePath(path: string): string {\n\tconst expanded = expandUserPath(path);\n\tconst normalized = normalize(expanded);\n\treturn isAbsolute(normalized)\n\t\t? normalized\n\t\t: resolve(process.cwd(), normalized);\n}\n\n/**\n * Check if path attempts to escape a base directory\n */\nexport function isPathTraversal(path: string, baseDir?: string): boolean {\n\tconst normalizedPath = normalizePath(path);\n\tconst base = baseDir ? normalizePath(baseDir) : process.cwd();\n\n\t// Check if the normalized path starts with the base directory\n\tconst isWindows = process.platform === \"win32\";\n\tconst normalizedPathCheck = isWindows\n\t\t? normalizedPath.toLowerCase()\n\t\t: normalizedPath;\n\tconst baseCheck = isWindows ? base.toLowerCase() : base;\n\n\treturn (\n\t\t!normalizedPathCheck.startsWith(baseCheck + sep) &&\n\t\tnormalizedPathCheck !== baseCheck\n\t);\n}\n\n/**\n * Validate that a path is safe and accessible\n */\nexport interface PathValidationOptions {\n\t/** Require the path to exist */\n\tmustExist?: boolean;\n\t/** Require the path to be readable */\n\tmustBeReadable?: boolean;\n\t/** Require the path to be writable */\n\tmustBeWritable?: boolean;\n\t/** Base directory to restrict access to */\n\tbaseDir?: string;\n\t/** Maximum file size in bytes */\n\tmaxSize?: number;\n\t/** Allowed file extensions */\n\tallowedExtensions?: Set<string>;\n\t/** Disallow symlinks */\n\tnoSymlinks?: boolean;\n}\n\n/**\n * Comprehensive path validation\n */\nexport async function validatePath(\n\tpath: string,\n\toptions: PathValidationOptions = {},\n): Promise<string> {\n\tconst {\n\t\tmustExist = false,\n\t\tmustBeReadable = false,\n\t\tmustBeWritable = false,\n\t\tbaseDir,\n\t\tmaxSize,\n\t\tallowedExtensions,\n\t\tnoSymlinks = false,\n\t} = options;\n\n\t// Normalize the path\n\tlet normalizedPath: string;\n\ttry {\n\t\tnormalizedPath = normalizePath(path);\n\t} catch (error) {\n\t\tlogger.warn(\"Path normalization failed\", { path, error });\n\t\tthrow new PathValidationError(\n\t\t\t`Invalid path: ${path}`,\n\t\t\tpath,\n\t\t\t\"normalization_failed\",\n\t\t);\n\t}\n\n\t// Check for path traversal\n\tif (baseDir && isPathTraversal(normalizedPath, baseDir)) {\n\t\tlogger.warn(\"Path traversal attempt detected\", {\n\t\t\tpath,\n\t\t\tnormalizedPath,\n\t\t\tbaseDir,\n\t\t});\n\t\tthrow new PathValidationError(\n\t\t\t`Path traversal detected: ${path}`,\n\t\t\tpath,\n\t\t\t\"path_traversal\",\n\t\t);\n\t}\n\n\t// Check existence if required\n\tif (mustExist || mustBeReadable || mustBeWritable || maxSize !== undefined) {\n\t\ttry {\n\t\t\tawait access(normalizedPath, constants.F_OK);\n\t\t} catch {\n\t\t\tthrow new PathValidationError(\n\t\t\t\t`File not found: ${path}`,\n\t\t\t\tnormalizedPath,\n\t\t\t\t\"not_found\",\n\t\t\t);\n\t\t}\n\t}\n\n\t// Check readability\n\tif (mustBeReadable) {\n\t\ttry {\n\t\t\tawait access(normalizedPath, constants.R_OK);\n\t\t} catch {\n\t\t\tthrow new PathValidationError(\n\t\t\t\t`File not readable: ${path}`,\n\t\t\t\tnormalizedPath,\n\t\t\t\t\"not_readable\",\n\t\t\t);\n\t\t}\n\t}\n\n\t// Check writability\n\tif (mustBeWritable) {\n\t\ttry {\n\t\t\tawait access(normalizedPath, constants.W_OK);\n\t\t} catch {\n\t\t\tthrow new PathValidationError(\n\t\t\t\t`File not writable: ${path}`,\n\t\t\t\tnormalizedPath,\n\t\t\t\t\"not_writable\",\n\t\t\t);\n\t\t}\n\t}\n\n\t// Check file size\n\tif (maxSize !== undefined) {\n\t\ttry {\n\t\t\tconst stats = await stat(normalizedPath);\n\t\t\tif (stats.size > maxSize) {\n\t\t\t\tthrow new PathValidationError(\n\t\t\t\t\t`${ERRORS.FILE_TOO_LARGE}: ${path} (${stats.size} bytes, max: ${maxSize} bytes)`,\n\t\t\t\t\tnormalizedPath,\n\t\t\t\t\t\"file_too_large\",\n\t\t\t\t);\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tif (error instanceof PathValidationError) throw error;\n\t\t\t// Ignore stat errors if file doesn't exist\n\t\t}\n\t}\n\n\t// Check file extension from the last path segment (so dirs like .git don't affect it)\n\tif (allowedExtensions && allowedExtensions.size > 0) {\n\t\tconst name = basename(normalizedPath);\n\t\tconst lastDot = name.lastIndexOf(\".\");\n\t\tconst ext = lastDot >= 0 ? name.slice(lastDot) : \"\";\n\t\tif (!allowedExtensions.has(ext)) {\n\t\t\tthrow new PathValidationError(\n\t\t\t\t`File extension not allowed: ${ext || \"(none)\"}`,\n\t\t\t\tnormalizedPath,\n\t\t\t\t\"extension_not_allowed\",\n\t\t\t);\n\t\t}\n\t}\n\n\t// Check for symlinks\n\tif (noSymlinks) {\n\t\ttry {\n\t\t\tconst realPath = await realpath(normalizedPath);\n\t\t\tif (realPath !== normalizedPath) {\n\t\t\t\tthrow new PathValidationError(\n\t\t\t\t\t`Symlinks not allowed: ${path}`,\n\t\t\t\t\tnormalizedPath,\n\t\t\t\t\t\"symlink_detected\",\n\t\t\t\t);\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tif (error instanceof PathValidationError) throw error;\n\t\t\t// Ignore errors if file doesn't exist yet\n\t\t}\n\t}\n\n\treturn normalizedPath;\n}\n\n/**\n * Synchronous path validation (basic checks only)\n */\nexport function validatePathSync(path: string, baseDir?: string): string {\n\tconst normalizedPath = normalizePath(path);\n\n\tif (baseDir && isPathTraversal(normalizedPath, baseDir)) {\n\t\tthrow new PathValidationError(\n\t\t\t`Path traversal detected: ${path}`,\n\t\t\tpath,\n\t\t\t\"path_traversal\",\n\t\t);\n\t}\n\n\treturn normalizedPath;\n}\n\n/**\n * Check if a path is within the current working directory\n */\nexport function isWithinCwd(path: string, cwd = process.cwd()): boolean {\n\tconst normalizedPath = normalizePath(path);\n\tconst normalizedCwd = normalizePath(cwd);\n\tconst isWindows = process.platform === \"win32\";\n\n\tconst pathCheck = isWindows ? normalizedPath.toLowerCase() : normalizedPath;\n\tconst cwdCheck = isWindows ? normalizedCwd.toLowerCase() : normalizedCwd;\n\n\treturn pathCheck.startsWith(cwdCheck + sep) || pathCheck === cwdCheck;\n}\n\n/**\n * Safely join paths with validation\n */\nexport function safejoin(base: string, ...parts: string[]): string {\n\tconst joined = resolve(base, ...parts);\n\tconst normalizedBase = normalizePath(base);\n\n\tconst isWindows = process.platform === \"win32\";\n\tconst joinedCheck = isWindows ? joined.toLowerCase() : joined;\n\tconst baseCheck = isWindows ? normalizedBase.toLowerCase() : normalizedBase;\n\n\tif (!joinedCheck.startsWith(baseCheck + sep) && joinedCheck !== baseCheck) {\n\t\tthrow new PathValidationError(\n\t\t\t`Path would escape base directory: ${parts.join(\"/\")}`,\n\t\t\tjoined,\n\t\t\t\"path_traversal\",\n\t\t);\n\t}\n\n\treturn joined;\n}\n\n/**\n * Validate multiple paths in parallel\n */\nexport async function validatePaths(\n\tpaths: string[],\n\toptions: PathValidationOptions = {},\n): Promise<string[]> {\n\treturn Promise.all(paths.map((path) => validatePath(path, options)));\n}\n"]}

package/dist/version.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.10.8",
-  "notes": "Maestro by EvalOps - Deterministic coding agent with TUI/CLI and Web UI for AI-assisted development v0.10.8 is now available."
+  "version": "0.10.11",
+  "notes": "Maestro by EvalOps - Deterministic coding agent with TUI/CLI and Web UI for AI-assisted development v0.10.11 is now available."
 }