opencode-search-plugin 0.0.0-stage → 1.0.0

package/plugins/anysearch-search.ts

@@ -0,0 +1,227 @@
+import { Plugin } from "@opencode/plugin/effect"
+import { Effect, Schema } from "effect"
+
+// AnySearch wraps every response in an envelope: code 0 / "success" on the happy
+// path, code -1 with a human-readable message otherwise. request_id is the only
+// handle support has on a request, so it rides along on every failure. Result
+// fields are optional -- a missing one means "the source provided none", not an
+// error.
+const AnySearchResponse = Schema.Struct({
+  code: Schema.Number,
+  message: Schema.optional(Schema.String),
+  request_id: Schema.optional(Schema.String),
+  data: Schema.optional(
+    Schema.Struct({
+      results: Schema.optional(
+        Schema.Array(
+          Schema.Struct({
+            title: Schema.optional(Schema.String),
+            url: Schema.String,
+            snippet: Schema.optional(Schema.String),
+            content: Schema.optional(Schema.String),
+          }),
+        ),
+      ),
+    }),
+  ),
+})
+
+// The /connect integration ID, and the websearch provider ID it binds to.
+const ID = "anysearch"
+
+// AnySearch returns no publication date, so results carry an empty time record.
+function toResult(item: {
+  title?: string | undefined
+  url: string
+  snippet?: string | undefined
+  content?: string | undefined
+}) {
+  return {
+    url: item.url,
+    title: item.title || item.url,
+    content: item.content ?? item.snippet ?? "",
+    time: {},
+  }
+}
+
+type SearchResult = ReturnType<typeof toResult>
+
+function envInt(name: string, fallback: number): number {
+  const raw = (process.env[name] ?? "").trim()
+  if (raw === "") return fallback
+  const value = Number(raw)
+  return Number.isFinite(value) && value >= 0 ? value : fallback
+}
+
+function envStr(name: string): string {
+  return (process.env[name] ?? "").trim()
+}
+
+// AnySearch is callable without a key: anonymous traffic is rate-limited per IP
+// against the daily free quota, and a key raises the quota. Each query is a
+// fresh upstream dispatch that routes intent on its own, so responses are
+// cached per normalized query. Knobs are read once at load time, restart after
+// changing them.
+//
+//   ANYSEARCH_CACHE_TTL     ms to reuse a response for the same query (0 disables)
+//   ANYSEARCH_MAX_RESULTS   results per search, clamped to 1-10 (the API's range)
+//   ANYSEARCH_TAG           pin the intent router to a sub-domain, e.g. "code.doc";
+//                           leave unset and AnySearch routes on the query itself
+//   ANYSEARCH_ZONE          "cn" or "intl"
+//   ANYSEARCH_LANGUAGE      preferred result language, e.g. "zh-CN"
+//   ANYSEARCH_FORMAT        "markdown" (default) or "json" for the content field
+//   ANYSEARCH_API_KEY       optional; anonymous access works without it
+const CACHE_TTL = envInt("ANYSEARCH_CACHE_TTL", 600_000)
+const SEARCH_SIZE = Math.min(Math.max(envInt("ANYSEARCH_MAX_RESULTS", 10), 1), 10)
+const TAG = envStr("ANYSEARCH_TAG")
+const ZONE = envStr("ANYSEARCH_ZONE")
+const LANGUAGE = envStr("ANYSEARCH_LANGUAGE")
+const FORMAT = envStr("ANYSEARCH_FORMAT") === "json" ? "json" : "markdown"
+
+const CACHE_LIMIT = 200
+const cache = new Map<string, { at: number; results: SearchResult[] }>()
+
+function cacheKey(query: string): string {
+  return query.trim().replace(/\s+/g, " ")
+}
+
+function readCache(queryKey: string): SearchResult[] | undefined {
+  if (CACHE_TTL <= 0) return undefined
+  const hit = cache.get(queryKey)
+  return hit && Date.now() - hit.at < CACHE_TTL ? hit.results : undefined
+}
+
+function writeCache(queryKey: string, results: SearchResult[]): void {
+  if (CACHE_TTL <= 0) return
+  cache.set(queryKey, { at: Date.now(), results })
+  if (cache.size > CACHE_LIMIT) {
+    const oldest = cache.keys().next().value
+    if (oldest !== undefined) cache.delete(oldest)
+  }
+}
+
+// Unlike the other providers in this repo, AnySearch never gates on `bound`:
+// anonymous access is a first-class mode, so the provider is always in the
+// pool. The key is still read per call, which is why no credential-event
+// subscription is needed -- a rotated key takes effect on the next search
+// without a reload.
+export const effect = (ctx: Plugin.Context) =>
+  Effect.gen(function* () {
+    // Make "AnySearch" show up in /connect with an API-key method.
+    yield* ctx.integration.transform((editor) => {
+      editor.update(ID, (integration) => {
+        integration.name = "AnySearch"
+      })
+      editor.method.update({
+        integrationID: ID,
+        method: { type: "key", label: "AnySearch API key" },
+      })
+      editor.method.update({
+        integrationID: ID,
+        method: { type: "env", names: ["ANYSEARCH_API_KEY"] },
+      })
+    })
+
+    // The host instantiates this API's failure channel as `unknown`, which would
+    // make the whole plugin effect unrunnable. A credential read must never take
+    // the plugin down: a failed read degrades to "no stored key", and the
+    // environment fallback below applies exactly as it does when the credential
+    // simply does not exist.
+    const soften = <A>(read: Effect.Effect<A, unknown>): Effect.Effect<A | undefined, never> =>
+      read.pipe(Effect.catch(() => Effect.succeed(undefined)))
+
+    yield* ctx.websearch.transform((editor) => {
+      editor.add({
+        id: ID,
+        name: "AnySearch",
+        execute: ({ query }) =>
+          Effect.gen(function* () {
+            const queryKey = cacheKey(query)
+            const cached = readCache(queryKey)
+            if (cached) return cached
+
+            // Anonymous access is a first-class mode, so a missing key is not
+            // an error: it just means no Authorization header goes out.
+            const connection = yield* soften(ctx.integration.connection.active(ID))
+            const credential = connection
+              ? yield* soften(ctx.integration.connection.resolve(connection))
+              : undefined
+            const key =
+              credential?.type === "key" ? credential.key : process.env.ANYSEARCH_API_KEY
+
+            const headers: Record<string, string> = {
+              Accept: "application/json",
+              "Content-Type": "application/json",
+            }
+            if (key) headers.Authorization = "Bearer " + key
+
+            const response = yield* Effect.tryPromise({
+              try: () =>
+                fetch("https://api.anysearch.com/v1/search", {
+                  method: "POST",
+                  headers,
+                  body: JSON.stringify({
+                    query: queryKey,
+                    max_results: SEARCH_SIZE,
+                    ...(TAG ? { tag: TAG } : {}),
+                    ...(ZONE ? { zone: ZONE } : {}),
+                    ...(LANGUAGE ? { language: LANGUAGE } : {}),
+                    format: FORMAT,
+                  }),
+                }),
+              catch: (error) => new Error("AnySearch request failed: " + String(error)),
+            })
+
+            if (!response.ok) {
+              // A 402 body can hand back freshly generated credentials, so it
+              // is deliberately never echoed into the conversation.
+              if (response.status === 402) {
+                return yield* Effect.fail(
+                  new Error(
+                    "AnySearch quota exhausted (HTTP 402). Set ANYSEARCH_API_KEY " +
+                      "or connect AnySearch in /connect to continue. The response " +
+                      "body is withheld because it may contain credentials.",
+                  ),
+                )
+              }
+              const detail = yield* Effect.tryPromise({
+                try: () => response.text(),
+                catch: () => new Error("response body unavailable"),
+              })
+              return yield* Effect.fail(
+                new Error("AnySearch API error " + response.status + ": " + detail),
+              )
+            }
+
+            const json = yield* Effect.tryPromise({
+              try: () => response.json(),
+              catch: (error) => new Error("Invalid AnySearch response: " + String(error)),
+            })
+
+            const body = yield* Schema.decodeUnknownEffect(AnySearchResponse)(json)
+
+            // AnySearch reports failures in the envelope too, even on HTTP
+            // 200. request_id is what support needs to trace the request.
+            if (body.code !== 0) {
+              return yield* Effect.fail(
+                new Error(
+                  "AnySearch API error " +
+                    body.code +
+                    ": " +
+                    (body.message ?? "unknown error") +
+                    " (request_id " +
+                    (body.request_id ?? "unknown") +
+                    ")",
+                ),
+              )
+            }
+
+            const results = (body.data?.results ?? []).map(toResult)
+            writeCache(queryKey, results)
+            return results
+          }),
+      })
+    })
+  })
+
+export default Plugin.define({ id: "anysearch-search", effect })

package/plugins/brave-search.ts

@@ -0,0 +1,270 @@
+import { Plugin } from "@opencode/plugin/effect"
+import { Effect, Schema, Stream } from "effect"
+
+// Brave returns { web: { results: [...] } } beside several result types this
+// plugin does not read (news, videos, discussions, infobox). Failures arrive as
+// plain HTTP status codes with no body-level envelope. Every result field is
+// optional -- a missing one means "Brave provided none", not an error.
+const BraveResponse = Schema.Struct({
+  web: Schema.optional(
+    Schema.Struct({
+      results: Schema.Array(
+        Schema.Struct({
+          title: Schema.String,
+          url: Schema.String,
+          description: Schema.optional(Schema.String),
+          page_age: Schema.optional(Schema.String),
+        }),
+      ),
+    }),
+  ),
+})
+
+// The /connect integration ID, and the websearch provider ID it binds to.
+const ID = "brave"
+
+function envInt(name: string, fallback: number): number {
+  const raw = (process.env[name] ?? "").trim()
+  if (raw === "") return fallback
+  const value = Number(raw)
+  return Number.isFinite(value) && value >= 0 ? value : fallback
+}
+
+function envStr(name: string): string {
+  return (process.env[name] ?? "").trim()
+}
+
+// Search engines hand out dates in three flavours: relative ("28 minutes ago"),
+// absolute ("Sep 30, 2026" in the US, "31 Mar 2026" elsewhere), and non-English
+// relative ("4天前"). Relative values are rounded upstream, so month/year use
+// 30/365 days. ISO 8601 timestamps are accepted as-is.
+// See https://serpapi.com/blog/how-to-parse-dates-from-google-search/
+const RELATIVE_MS: Record<string, number> = {
+  minute: 60_000,
+  hour: 3_600_000,
+  day: 86_400_000,
+  week: 604_800_000,
+  month: 2_592_000_000,
+  year: 31_536_000_000,
+  分钟: 60_000,
+  小时: 3_600_000,
+  天: 86_400_000,
+  周: 604_800_000,
+  个月: 2_592_000_000,
+  月: 2_592_000_000,
+  年: 31_536_000_000,
+}
+
+const RELATIVE_DATE =
+  /^(\d+)\s*(minute|hour|day|week|month|year|分钟|小时|天|周|个月|月|年)s?\s*(?:ago|前)$/i
+
+const ABSOLUTE_DATE = [
+  /^\d{1,2}\s+[A-Za-z]{3,9}\s+\d{4}$/, // "3 Jan 2022", "31 Mar 2026"
+  /^[A-Za-z]{3,9}\s+\d{1,2},?\s+\d{4}$/, // "Sep 30, 2026", "Jan 27, 2025"
+  /^\d{4}-\d{2}-\d{2}$/, // "2026-10-16"
+  // ISO 8601 with a time component, which Brave returns on `page_age`.
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?$/,
+]
+
+function parseSearchDate(value: string | undefined): number {
+  const text = value?.trim()
+  if (!text) return NaN
+
+  const relative = RELATIVE_DATE.exec(text)
+  if (relative) {
+    const unit = relative[2] !== undefined ? RELATIVE_MS[relative[2].toLowerCase()] : undefined
+    const amount = Number(relative[1])
+    if (unit === undefined || !Number.isFinite(amount)) return NaN
+    return Date.now() - amount * unit
+  }
+
+  // Only trust Date.parse on shapes these providers actually emit -- its lenient
+  // parser invents a year for strings like "Nov 1", which would date the result
+  // to 2001.
+  return ABSOLUTE_DATE.some((shape) => shape.test(text)) ? Date.parse(text) : NaN
+}
+
+function toResult(item: {
+  title: string
+  url: string
+  description?: string | undefined
+  page_age?: string | undefined
+}) {
+  const published = parseSearchDate(item.page_age)
+  return {
+    url: item.url,
+    title: item.title,
+    content: item.description ?? "",
+    time: Number.isFinite(published) ? { published } : {},
+  }
+}
+
+type SearchResult = ReturnType<typeof toResult>
+
+// Brave bills per query and has no anonymous tier, so a repeat query is a fresh
+// billed dispatch. Responses are cached per normalized query. Knobs are read
+// once at load time, restart after changing them.
+//
+//   BRAVE_CACHE_TTL       ms to reuse a response for the same query (0 disables)
+//   BRAVE_NUM             results per search, clamped to 1-20 (Brave's maximum)
+//   BRAVE_COUNTRY         2-letter country code, e.g. "us", "cn"; or "ALL"
+//   BRAVE_LANG            result language code, e.g. "en", "zh-hans", "pt-br"
+//   BRAVE_FRESHNESS       "pd" (24h) "pw" (7d) "pm" (31d) "py" (365d) or a
+//                         "YYYY-MM-DDtoYYYY-MM-DD" range
+//   BRAVE_SEARCH_API_KEY  required; from https://brave.com/search/api/
+const CACHE_TTL = envInt("BRAVE_CACHE_TTL", 600_000)
+const SEARCH_SIZE = Math.min(Math.max(envInt("BRAVE_NUM", 8), 1), 20)
+const COUNTRY = envStr("BRAVE_COUNTRY")
+const SEARCH_LANG = envStr("BRAVE_LANG")
+const FRESHNESS = envStr("BRAVE_FRESHNESS")
+
+const CACHE_LIMIT = 200
+const cache = new Map<string, { at: number; results: SearchResult[] }>()
+
+function cacheKey(query: string): string {
+  return query.trim().replace(/\s+/g, " ")
+}
+
+function readCache(queryKey: string): SearchResult[] | undefined {
+  if (CACHE_TTL <= 0) return undefined
+  const hit = cache.get(queryKey)
+  return hit && Date.now() - hit.at < CACHE_TTL ? hit.results : undefined
+}
+
+function writeCache(queryKey: string, results: SearchResult[]): void {
+  if (CACHE_TTL <= 0) return
+  cache.set(queryKey, { at: Date.now(), results })
+  if (cache.size > CACHE_LIMIT) {
+    const oldest = cache.keys().next().value
+    if (oldest !== undefined) cache.delete(oldest)
+  }
+}
+
+export const effect = (ctx: Plugin.Context) =>
+  Effect.gen(function* () {
+    // Make "Brave Search" show up in /connect with an API-key method.
+    yield* ctx.integration.transform((editor) => {
+      editor.update(ID, (integration) => {
+        integration.name = "Brave Search"
+      })
+      editor.method.update({
+        integrationID: ID,
+        method: { type: "key", label: "Brave Search API key" },
+      })
+      editor.method.update({
+        integrationID: ID,
+        method: { type: "env", names: ["BRAVE_SEARCH_API_KEY"] },
+      })
+    })
+
+    // The host instantiates this API's failure channel as `unknown`, which would
+    // make the whole plugin effect unrunnable. A credential read must never take
+    // the plugin down: a failed read degrades to "no stored key", and the
+    // environment fallback below applies exactly as it does when the credential
+    // simply does not exist.
+    const soften = <A>(read: Effect.Effect<A, unknown>): Effect.Effect<A | undefined, never> =>
+      read.pipe(Effect.catch(() => Effect.succeed(undefined)))
+
+    // The key comes from the /connect credential, falling back to the
+    // environment. Resolved per call so a rotated key needs no restart.
+    const resolveKey = () =>
+      Effect.gen(function* () {
+        const connection = yield* soften(ctx.integration.connection.active(ID))
+        const credential = connection
+          ? yield* soften(ctx.integration.connection.resolve(connection))
+          : undefined
+        return credential?.type === "key" ? credential.key : process.env.BRAVE_SEARCH_API_KEY
+      })
+
+    // Brave is bound to websearch only while a key exists. Deleting the key
+    // unbinds the provider, so `random` can never pick a keyless Brave.
+    // The transform replays on reload and reads `bound` as it stands then.
+    let bound = Boolean(yield* resolveKey())
+
+    yield* ctx.websearch.transform((editor) => {
+      if (!bound) return
+      editor.add({
+        id: ID,
+        name: "Brave Search",
+        execute: ({ query }) =>
+          Effect.gen(function* () {
+            const queryKey = cacheKey(query)
+            const cached = readCache(queryKey)
+            if (cached) return cached
+
+            // Rechecked per call: the binding can lag a key deletion by the
+            // event round-trip, and this keeps that window explicit.
+            const key = yield* resolveKey()
+            if (!key) {
+              return yield* Effect.fail(
+                new Error("Connect Brave in /connect, or set BRAVE_SEARCH_API_KEY"),
+              )
+            }
+
+            const url = new URL("https://api.search.brave.com/res/v1/web/search")
+            url.searchParams.set("q", queryKey)
+            url.searchParams.set("count", String(SEARCH_SIZE))
+            if (COUNTRY) url.searchParams.set("country", COUNTRY)
+            if (SEARCH_LANG) url.searchParams.set("search_lang", SEARCH_LANG)
+            if (FRESHNESS) url.searchParams.set("freshness", FRESHNESS)
+
+            const response = yield* Effect.tryPromise({
+              try: () =>
+                fetch(url, {
+                  headers: {
+                    Accept: "application/json",
+                    "X-Subscription-Token": key,
+                  },
+                }),
+              catch: (error) => new Error("Brave request failed: " + String(error)),
+            })
+
+            if (!response.ok) {
+              const detail = yield* Effect.tryPromise({
+                try: () => response.text(),
+                catch: () => new Error("response body unavailable"),
+              })
+              return yield* Effect.fail(
+                new Error("Brave API error " + response.status + ": " + detail),
+              )
+            }
+
+            const json = yield* Effect.tryPromise({
+              try: () => response.json(),
+              catch: (error) => new Error("Invalid Brave response: " + String(error)),
+            })
+
+            const body = yield* Schema.decodeUnknownEffect(BraveResponse)(json)
+            const results = (body.web?.results ?? []).map(toResult)
+
+            writeCache(queryKey, results)
+            return results
+          }),
+      })
+    })
+
+    // Rebind on credential changes: connect, delete, or rotate a key and the
+    // provider joins or leaves the websearch pool without a restart. Env-var
+    // keys cannot change under a running process, so they bind at startup.
+    yield* Effect.forkScoped(
+      ctx.event.subscribe().pipe(
+        Stream.filter(
+          (event) =>
+            event.type === "credential.updated" ||
+            event.type === "credential.switched" ||
+            event.type === "integration.updated",
+        ),
+        Stream.mapEffect(() =>
+          Effect.gen(function* () {
+            const next = Boolean(yield* resolveKey())
+            if (next === bound) return
+            bound = next
+            yield* ctx.websearch.reload()
+          }),
+        ),
+        Stream.runDrain,
+      ),
+    )
+  })
+
+export default Plugin.define({ id: "brave-search", effect })