@effect-x/ultimate-search 0.1.0 → 0.1.1

package/src/shared/effect.ts

@@ -0,0 +1,52 @@
+import { Effect } from "effect";
+/**
+ * Derives the return type for a service method, strictly preserving the
+ * method's full type signature (success, error, and context).
+ *
+ * Unlike RPC return helpers (where transport contracts typically do not carry a
+ * context channel and `R` is introduced separately), service interfaces already
+ * define the full `Effect.Effect<A, E, R>` — including dependencies. The
+ * implementation must conform exactly; any extra dependency is a compile error,
+ * not something to patch in via a generic.
+ *
+ * @typeParam T - The service method type (from `ServiceMap.Service.Shape<typeof MyService>[key]`)
+ * @typeParam R - Optional additional context requirements to merge with the method's context
+ *
+ * @example
+ * ```ts
+ * import { Effect, ServiceMap } from "effect"
+ *
+ * export class MyService extends ServiceMap.Service<MyService, {
+ *   readonly list: () => Effect.Effect<Items, MyError>
+ *   readonly data: Effect.Effect<Data, MyError>
+ * }>()("MyService") {}
+ *
+ * export declare namespace MyService {
+ *   export type Methods = ServiceMap.Service.Shape<typeof MyService>
+ *   export type Returns<key extends keyof Methods, R = never> = ServicesReturns<Methods[key], R>
+ * }
+ *
+ * const list: MyService.Methods['list'] = Effect.fn('list')(
+ *   function* (): MyService.Returns<'list'> {
+ *     // return type is locked to Effect.Effect<Items, MyError, never>
+ *     ...
+ *   }
+ * )
+ *
+ * // With additional context
+ * const listWithLogger: MyService.Methods['list'] = Effect.fn('list')(
+ *   function* (): MyService.Returns<'list', Logger> {
+ *     // return type is Effect.Effect<Items, MyError, Logger>
+ *     const logger = yield* Logger
+ *     ...
+ *   }
+ * )
+ * ```
+ */
+export type ServicesReturns<T, R = never> = T extends (
+  ...args: any
+) => Effect.Effect<infer A, infer E, infer R0>
+  ? Effect.fn.Return<A, E, R0 | R>
+  : T extends Effect.Effect<infer A, infer E, infer R0>
+    ? Effect.fn.Return<A, E, R0 | R>
+    : T;

package/src/shared/errors.ts

@@ -0,0 +1,56 @@
+import { Schema } from "effect";
+
+export const SearchProvider = Schema.Literals(["shared", "grok", "tavily", "firecrawl"]);
+
+export class ConfigValidationError extends Schema.TaggedErrorClass<ConfigValidationError>()(
+  "ConfigValidationError",
+  {
+    provider: SearchProvider,
+    message: Schema.String,
+    details: Schema.optional(Schema.Array(Schema.String)),
+    cause: Schema.optional(Schema.Unknown),
+  },
+) {}
+
+export class ProviderRequestError extends Schema.TaggedErrorClass<ProviderRequestError>()(
+  "ProviderRequestError",
+  {
+    provider: SearchProvider,
+    message: Schema.String,
+  },
+) {}
+
+export class ProviderResponseError extends Schema.TaggedErrorClass<ProviderResponseError>()(
+  "ProviderResponseError",
+  {
+    provider: SearchProvider,
+    message: Schema.String,
+    status: Schema.Number,
+    body: Schema.String,
+    cause: Schema.optional(Schema.Unknown),
+  },
+) {}
+
+export class ProviderContentError extends Schema.TaggedErrorClass<ProviderContentError>()(
+  "ProviderContentError",
+  {
+    provider: SearchProvider,
+    message: Schema.String,
+  },
+) {}
+
+export class ProviderDecodeError extends Schema.TaggedErrorClass<ProviderDecodeError>()(
+  "ProviderDecodeError",
+  {
+    provider: SearchProvider,
+    message: Schema.String,
+    cause: Schema.optional(Schema.Unknown),
+  },
+) {}
+
+export type UltimateSearchError =
+  | ConfigValidationError
+  | ProviderContentError
+  | ProviderRequestError
+  | ProviderResponseError
+  | ProviderDecodeError;

package/src/shared/output.ts

@@ -0,0 +1,210 @@
+import { Config, Effect, Layer, Logger, Option, Schema, ServiceMap, Console } from "effect";
+import { Flag } from "effect/unstable/cli";
+import {
+  ConfigValidationError,
+  ProviderContentError,
+  ProviderDecodeError,
+  ProviderRequestError,
+  ProviderResponseError,
+} from "./errors";
+import { renderStructuredError } from "./render-error";
+
+const stringify = (value: unknown) => JSON.stringify(value, null, 2);
+const maxHumanErrorBodyLength = 500;
+
+export const OutputModeSchema = Schema.Literals(["human", "llm"] as const);
+export type OutputMode = typeof OutputModeSchema.Type;
+
+export const outputFlag = Flag.optional(
+  Flag.choice("output", OutputModeSchema.literals).pipe(
+    Flag.withDescription("Output mode: human for readable text, llm for structured JSON."),
+  ),
+);
+
+const trimTrailingWhitespace = (text: string) => text.trimEnd();
+
+const truncate = (text: string, maxLength: number) =>
+  text.length <= maxLength ? text : `${text.slice(0, maxLength - 1)}...`;
+
+const configErrorDetails = (error: ConfigValidationError): Array<string> => {
+  const details = Array.isArray(error.details)
+    ? error.details.filter((detail) => detail.length > 0)
+    : [];
+
+  if (details.length > 0) {
+    return details;
+  }
+
+  if (error.cause instanceof Error && error.cause.message.length > 0) {
+    return [error.cause.message];
+  }
+
+  if (typeof error.cause === "string" && error.cause.length > 0) {
+    return [error.cause];
+  }
+
+  return [];
+};
+
+export const writeJsonStdout = (value: unknown) => Console.log(stringify(value));
+export const renderJsonText = (value: unknown) => stringify(value);
+
+const defaultOutputModeConfig = Config.string("AGENT").pipe(
+  Config.withDefault(""),
+  Config.map((agent): OutputMode => (agent.trim().length > 0 ? "llm" : "human")),
+);
+
+export const resolveOutputMode = (
+  selected: Option.Option<OutputMode>,
+  fallback: OutputMode,
+): OutputMode => Option.getOrElse(selected, () => fallback);
+
+const makeCliOutput = (defaultMode: OutputMode) =>
+  CliOutput.of({
+    defaultMode,
+    writeOutput: ({ human, llm }, mode = defaultMode) =>
+      mode === "llm" ? writeJsonStdout(llm) : Console.log(human),
+    logError: (error, mode = defaultMode) => logCliError(error, mode),
+  });
+
+const renderHumanError = (error: unknown) => {
+  if (error instanceof ConfigValidationError) {
+    const details = configErrorDetails(error);
+    const lines = [`Configuration error (${error.provider})`, error.message];
+
+    if (details.length > 0) {
+      lines.push("", "What to fix:");
+      lines.push(...details.map((detail) => `- ${detail}`));
+    }
+
+    return trimTrailingWhitespace(lines.join("\n"));
+  }
+
+  if (error instanceof ProviderRequestError) {
+    return trimTrailingWhitespace([`Request failed (${error.provider})`, error.message].join("\n"));
+  }
+
+  if (error instanceof ProviderContentError) {
+    return trimTrailingWhitespace(
+      [`Provider returned no usable content (${error.provider})`, error.message].join("\n"),
+    );
+  }
+
+  if (error instanceof ProviderResponseError) {
+    const lines = [
+      `Provider response error (${error.provider})`,
+      error.message,
+      `HTTP status: ${error.status}`,
+    ];
+    const body = error.body.trim();
+
+    if (body.length > 0) {
+      lines.push(`Response body: ${truncate(body, maxHumanErrorBodyLength)}`);
+    }
+
+    return trimTrailingWhitespace(lines.join("\n"));
+  }
+
+  if (error instanceof ProviderDecodeError) {
+    return trimTrailingWhitespace(
+      [`Provider decode error (${error.provider})`, error.message].join("\n"),
+    );
+  }
+
+  if (error instanceof Error) {
+    return trimTrailingWhitespace([error.name, error.message].join("\n"));
+  }
+
+  return `Unknown error\n${String(error)}`;
+};
+
+const cliErrorLogMessageTag = "UltimateSearchCliError";
+
+interface CliErrorLogMessage {
+  readonly _tag: typeof cliErrorLogMessageTag;
+  readonly mode: OutputMode;
+  readonly error: unknown;
+}
+
+const isCliErrorLogMessage = (value: unknown): value is CliErrorLogMessage =>
+  typeof value === "object" &&
+  value !== null &&
+  "_tag" in value &&
+  value._tag === cliErrorLogMessageTag &&
+  "mode" in value &&
+  (value.mode === "human" || value.mode === "llm") &&
+  "error" in value;
+
+const normalizeLogMessage = (message: unknown): unknown =>
+  Array.isArray(message) && message.length === 1 ? message[0] : message;
+
+const renderGenericLogMessage = (message: unknown): string => {
+  const normalized = normalizeLogMessage(message);
+
+  if (Array.isArray(normalized)) {
+    return normalized.map((item) => renderGenericLogMessage(item)).join(" ");
+  }
+
+  if (typeof normalized === "string") {
+    return normalized;
+  }
+
+  if (normalized instanceof Error) {
+    return trimTrailingWhitespace([normalized.name, normalized.message].join("\n"));
+  }
+
+  try {
+    return stringify(normalized);
+  } catch {
+    return String(normalized);
+  }
+};
+
+const formatCliLogMessage = (message: unknown): string => {
+  const normalized = normalizeLogMessage(message);
+
+  if (isCliErrorLogMessage(normalized)) {
+    return normalized.mode === "llm"
+      ? stringify({ error: renderStructuredError(normalized.error) })
+      : renderHumanError(normalized.error);
+  }
+
+  return renderGenericLogMessage(normalized);
+};
+
+export const logCliError = (error: unknown, mode: OutputMode) =>
+  Effect.logError({
+    _tag: cliErrorLogMessageTag,
+    mode,
+    error,
+  } satisfies CliErrorLogMessage);
+
+const cliConsoleLogger = Logger.withConsoleError(
+  Logger.make((options) => formatCliLogMessage(options.message)),
+);
+
+export const cliLoggerLayer = Logger.layer([cliConsoleLogger, Logger.tracerLogger]);
+
+export class CliOutput extends ServiceMap.Service<
+  CliOutput,
+  {
+    readonly defaultMode: OutputMode;
+    readonly writeOutput: (
+      output: {
+        readonly human: string;
+        readonly llm: unknown;
+      },
+      mode?: OutputMode,
+    ) => Effect.Effect<void>;
+    readonly logError: (error: unknown, mode?: OutputMode) => Effect.Effect<void>;
+  }
+>()("CliOutput") {
+  static readonly layer = Layer.effect(
+    CliOutput,
+    Effect.map(defaultOutputModeConfig.asEffect(), makeCliOutput),
+  );
+
+  static layerForMode(mode: OutputMode) {
+    return Layer.succeed(CliOutput, makeCliOutput(mode));
+  }
+}

package/src/shared/provider-http-client.ts

@@ -0,0 +1,73 @@
+import { Effect } from "effect";
+import { HttpClient, HttpClientError, type HttpClientResponse } from "effect/unstable/http";
+import { ProviderRequestError, ProviderResponseError } from "./errors";
+
+export type ProviderHttpClientName = "shared" | "grok" | "tavily" | "firecrawl";
+
+export const mapProviderRequestError = (
+  provider: ProviderHttpClientName,
+  error: unknown,
+  fallback: string,
+) =>
+  new ProviderRequestError({
+    provider,
+    message: error instanceof Error && error.message.length > 0 ? error.message : fallback,
+  });
+
+export const makeProviderHttpClient = (
+  client: HttpClient.HttpClient,
+): HttpClient.HttpClient.With<HttpClientError.HttpClientError, never> =>
+  client.pipe(
+    HttpClient.filterStatusOk,
+    HttpClient.retryTransient({
+      retryOn: "errors-and-responses",
+      times: 2,
+    }),
+  ) as HttpClient.HttpClient.With<HttpClientError.HttpClientError, never>;
+
+export const catchProviderHttpError =
+  (
+    provider: ProviderHttpClientName,
+    requestErrorMessage: string,
+    responseErrorMessage: (status: number) => string,
+  ) =>
+  <A>(
+    effect: Effect.Effect<A, HttpClientError.HttpClientError, never>,
+  ): Effect.Effect<A, ProviderRequestError | ProviderResponseError, never> =>
+    effect.pipe(
+      Effect.catchTag(
+        "HttpClientError",
+        (error): Effect.Effect<never, ProviderRequestError | ProviderResponseError, never> => {
+          const response = error.response;
+
+          if (response === undefined) {
+            return Effect.fail(mapProviderRequestError(provider, error, requestErrorMessage));
+          }
+
+          return response.text.pipe(
+            Effect.catch(() => Effect.succeed("")),
+            Effect.flatMap((body) =>
+              Effect.fail(
+                new ProviderResponseError({
+                  provider,
+                  message: responseErrorMessage(response.status),
+                  status: response.status,
+                  body,
+                  cause: error,
+                }),
+              ),
+            ),
+          );
+        },
+      ),
+    );
+
+export const decodeJsonResponse = <A, E1, E2>(
+  response: HttpClientResponse.HttpClientResponse,
+  decode: (value: unknown) => Effect.Effect<A, E1, never>,
+  mapDecodeError: (error: unknown) => E2,
+): Effect.Effect<A, E2, never> =>
+  response.json.pipe(
+    Effect.mapError(mapDecodeError),
+    Effect.flatMap((json) => decode(json).pipe(Effect.mapError(mapDecodeError))),
+  );

package/src/shared/render-error.ts

@@ -0,0 +1,101 @@
+import { Config } from "effect";
+import { Schema } from "effect";
+import {
+  ConfigValidationError,
+  ProviderDecodeError,
+  ProviderRequestError,
+  ProviderResponseError,
+} from "./errors";
+
+export interface RenderedError {
+  readonly type: string;
+  readonly provider?: string;
+  readonly message: string;
+  readonly details?: ReadonlyArray<string>;
+  readonly status?: number;
+  readonly body?: string;
+}
+
+export const RenderedErrorSchema = Schema.Struct({
+  type: Schema.String,
+  provider: Schema.optional(Schema.String),
+  message: Schema.String,
+  details: Schema.optional(Schema.Array(Schema.String)),
+  status: Schema.optional(Schema.Number),
+  body: Schema.optional(Schema.String),
+});
+
+const configErrorDetails = (error: ConfigValidationError): Array<string> => {
+  const details = Array.isArray(error.details)
+    ? error.details.filter((detail) => detail.length > 0)
+    : [];
+
+  if (details.length > 0) {
+    return details;
+  }
+
+  if (error.cause instanceof Config.ConfigError && error.cause.message.length > 0) {
+    return [error.cause.message];
+  }
+
+  if (error.cause instanceof Error && error.cause.message.length > 0) {
+    return [error.cause.message];
+  }
+
+  if (typeof error.cause === "string" && error.cause.length > 0) {
+    return [error.cause];
+  }
+
+  return [];
+};
+
+export const renderStructuredError = (error: unknown): RenderedError => {
+  if (error instanceof ConfigValidationError) {
+    const details = configErrorDetails(error);
+
+    return {
+      type: error._tag,
+      provider: error.provider,
+      message: error.message,
+      ...(details.length > 0 ? { details } : {}),
+    };
+  }
+
+  if (error instanceof ProviderRequestError) {
+    return {
+      type: error._tag,
+      provider: error.provider,
+      message: error.message,
+    };
+  }
+
+  if (error instanceof ProviderResponseError) {
+    return {
+      type: error._tag,
+      provider: error.provider,
+      message: error.message,
+      status: error.status,
+      body: error.body,
+    };
+  }
+
+  if (error instanceof ProviderDecodeError) {
+    return {
+      type: error._tag,
+      provider: error.provider,
+      message: error.message,
+    };
+  }
+
+  if (error instanceof Error) {
+    return {
+      type: error.name,
+      message: error.message,
+    };
+  }
+
+  return {
+    type: "UnknownError",
+    message: String(error),
+  };
+};

package/src/shared/schema.ts

@@ -0,0 +1,42 @@
+import { Effect, Option, Schema, SchemaIssue, SchemaTransformation } from "effect";
+
+const stripTrailingSlashes = (value: string) => value.replace(/\/+$/u, "");
+
+export const trimmedNonEmptyStringSchema = (message: string) =>
+  Schema.Trim.pipe(Schema.decodeTo(Schema.NonEmptyString), Schema.annotate({ message }));
+
+export const optionalTrimmedNonEmptyStringFromStringSchema = Schema.Trim.pipe(
+  Schema.decodeTo(
+    Schema.Option(Schema.NonEmptyString),
+    SchemaTransformation.transform({
+      decode: (value) => (value.length === 0 ? Option.none<string>() : Option.some(value)),
+      encode: (value) => Option.getOrElse(value, () => ""),
+    }),
+  ),
+);
+
+export const absoluteUrlStringSchema = (message: string) =>
+  Schema.Trim.pipe(
+    Schema.decodeTo(
+      Schema.String,
+      SchemaTransformation.transformOrFail({
+        decode: (value) =>
+          Effect.try({
+            try: () => stripTrailingSlashes(new URL(value).toString()),
+            catch: () => new SchemaIssue.InvalidValue(Option.some(value), { message }),
+          }),
+        encode: (value) => Effect.succeed(value),
+      }),
+    ),
+  );
+
+export const optionalAbsoluteUrlStringFromStringSchema = (message: string) =>
+  Schema.Trim.pipe(
+    Schema.decodeTo(
+      Schema.Option(absoluteUrlStringSchema(message)),
+      SchemaTransformation.transform({
+        decode: (value) => (value.length === 0 ? Option.none<string>() : Option.some(value)),
+        encode: (value) => Option.getOrElse(value, () => ""),
+      }),
+    ),
+  );

package/src/shared/tracing.ts

@@ -0,0 +1,53 @@
+import { Cause, Duration, Effect, Fiber, Layer, Logger, LogLevel, Tracer } from "effect";
+import { CurrentLoggers } from "effect/Logger";
+import { MinimumLogLevel } from "effect/References";
+
+export const TracingLayer = Layer.unwrap(
+  Effect.gen(function* () {
+    const logLevel = yield* MinimumLogLevel;
+
+    if (LogLevel.isLessThan("Trace", logLevel)) {
+      return Layer.empty;
+    }
+
+    return tracerLayer;
+  }),
+);
+
+const tracerLayer = Effect.gen(function* () {
+  const loggers = yield* CurrentLoggers;
+  const tracer = yield* Tracer.Tracer;
+  const fiber = Fiber.getCurrent()!;
+
+  const log = (message: string, time: bigint) => {
+    const date = new Date(Number(time / BigInt(1e6)));
+    const options: Logger.Options<string> = {
+      message,
+      fiber,
+      date,
+      logLevel: "Trace",
+      cause: Cause.empty,
+    };
+
+    loggers.forEach((logger) => {
+      logger.log(options);
+    });
+  };
+
+  return Tracer.make({
+    span(options) {
+      const span = tracer.span(options);
+      log(`${options.name}: started`, options.startTime);
+      const originalEnd = span.end;
+
+      span.end = (endTime, cause) => {
+        const duration = Duration.nanos(endTime - span.status.startTime);
+        log(`${options.name}: completed. Took ${Duration.format(duration)}`, endTime);
+
+        return originalEnd.call(span, endTime, cause);
+      };
+
+      return span;
+    },
+  });
+}).pipe(Layer.effect(Tracer.Tracer));