scoutline 0.7.0 → 0.10.0

package/dist/providers/exa/diagnostics.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Exa Diagnostics Capability (tech-plan §7, Diagnostics Probe).
+ *
+ * Probes Exa connectivity with a single, cheapest-possible request —
+ * `POST /search` with `type: "auto"` and a stub query — so the doctor
+ * command can verify a credential authenticates without burning deep
+ * credits. Mirrors `providers/tavily/diagnostics.ts`.
+ *
+ * The probe intentionally avoids the (deferred) usage endpoint entirely.
+ * `/search` with `type: "auto"` is the cheapest credible connectivity
+ * check; doctor catches the throw and records a redacted error entry.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import the diagnostics capability contract, Adapter-local
+ *     config, Adapter-local search transport, and normalized errors.
+ *   - Must NOT import command presentation or another Provider's
+ *     Adapter.
+ */
+import type { DiagnosticsCapability } from "../../capabilities/diagnostics.js";
+import { type ExaTransportDeps } from "./client.js";
+/**
+ * Options for the Exa DiagnosticsCapability. The API key is
+ * resolved from `env`; transport dependencies (`fetch`, timer) are
+ * injectable for deterministic tests through the unified `transport`
+ * seam.
+ */
+export interface ExaDiagnosticsCapabilityOptions {
+    readonly env: NodeJS.ProcessEnv;
+    readonly transport?: ExaTransportDeps;
+}
+/**
+ * Build the Exa DiagnosticsCapability. The probe performs ONE
+ * `/search` request with `type: "auto"` and a stub query so it costs
+ * the cheapest credible request. Shared execution owns the retry policy;
+ * this transport performs exactly one attempt per invocation.
+ *
+ * When `options.probe` is false, `invoke` resolves immediately without
+ * touching the network — the doctor command skips probing unconfigured
+ * or tools-disabled Providers before reaching this Capability.
+ */
+export declare function createExaDiagnosticsCapability(options: ExaDiagnosticsCapabilityOptions): DiagnosticsCapability;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/providers/exa/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../src/providers/exa/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAqB,MAAM,mCAAmC,CAAC;AAUlG,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AA8BpE;;;;;GAKG;AACH,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;CACvC;AAED;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,+BAA+B,GACvC,qBAAqB,CAcvB"}

package/dist/providers/exa/diagnostics.js

@@ -0,0 +1,69 @@
+/**
+ * Exa Diagnostics Capability (tech-plan §7, Diagnostics Probe).
+ *
+ * Probes Exa connectivity with a single, cheapest-possible request —
+ * `POST /search` with `type: "auto"` and a stub query — so the doctor
+ * command can verify a credential authenticates without burning deep
+ * credits. Mirrors `providers/tavily/diagnostics.ts`.
+ *
+ * The probe intentionally avoids the (deferred) usage endpoint entirely.
+ * `/search` with `type: "auto"` is the cheapest credible connectivity
+ * check; doctor catches the throw and records a redacted error entry.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import the diagnostics capability contract, Adapter-local
+ *     config, Adapter-local search transport, and normalized errors.
+ *   - Must NOT import command presentation or another Provider's
+ *     Adapter.
+ */
+import { ApiError, AuthError, ConfigurationError, NetworkError, QuotaError, TimeoutError, } from "../../lib/errors.js";
+import { requireExaApiKey } from "./credentials.js";
+import { fetchExaSearch } from "./client.js";
+// ---------------------------------------------------------------------------
+// Failure normalization (mirror the Adapter's search-path mapping)
+// ---------------------------------------------------------------------------
+/**
+ * Probe failure wrapper. Mirrors the Adapter's `normalizeExaError`
+ * for the subset of errors the probe can surface. The probe throws on
+ * failure; the doctor command catches the throw and records a redacted
+ * error entry. We never embed raw Provider bodies.
+ */
+function normalizeProbeError(error) {
+    if (error instanceof AuthError ||
+        error instanceof QuotaError ||
+        error instanceof ApiError ||
+        error instanceof NetworkError ||
+        error instanceof TimeoutError ||
+        error instanceof ConfigurationError) {
+        return error;
+    }
+    return new ApiError("Exa diagnostics probe failed", 500);
+}
+/**
+ * Build the Exa DiagnosticsCapability. The probe performs ONE
+ * `/search` request with `type: "auto"` and a stub query so it costs
+ * the cheapest credible request. Shared execution owns the retry policy;
+ * this transport performs exactly one attempt per invocation.
+ *
+ * When `options.probe` is false, `invoke` resolves immediately without
+ * touching the network — the doctor command skips probing unconfigured
+ * or tools-disabled Providers before reaching this Capability.
+ */
+export function createExaDiagnosticsCapability(options) {
+    const { env, transport } = options;
+    return {
+        async invoke(diagOptions) {
+            if (!diagOptions.probe)
+                return;
+            const apiKey = requireExaApiKey(env);
+            try {
+                // `type: "auto"` -> cheapest credible probe.
+                await fetchExaSearch(apiKey, "scoutline-doctor-probe", { type: "auto" }, transport);
+            }
+            catch (error) {
+                throw normalizeProbeError(error);
+            }
+        },
+    };
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/providers/exa/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../../src/providers/exa/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EACL,QAAQ,EACR,SAAS,EACT,kBAAkB,EAClB,YAAY,EACZ,UAAU,EACV,YAAY,GACb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAyB,MAAM,aAAa,CAAC;AAEpE,8EAA8E;AAC9E,mEAAmE;AACnE,8EAA8E;AAE9E;;;;;GAKG;AACH,SAAS,mBAAmB,CAAC,KAAc;IACzC,IACE,KAAK,YAAY,SAAS;QAC1B,KAAK,YAAY,UAAU;QAC3B,KAAK,YAAY,QAAQ;QACzB,KAAK,YAAY,YAAY;QAC7B,KAAK,YAAY,YAAY;QAC7B,KAAK,YAAY,kBAAkB,EACnC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,IAAI,QAAQ,CAAC,8BAA8B,EAAE,GAAG,CAAC,CAAC;AAC3D,CAAC;AAiBD;;;;;;;;;GASG;AACH,MAAM,UAAU,8BAA8B,CAC5C,OAAwC;IAExC,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IACnC,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,WAA8B;YACzC,IAAI,CAAC,WAAW,CAAC,KAAK;gBAAE,OAAO;YAC/B,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;YACrC,IAAI,CAAC;gBACH,6CAA6C;gBAC7C,MAAM,cAAc,CAAC,MAAM,EAAE,wBAAwB,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,CAAC,CAAC;YACtF,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,mBAAmB,CAAC,KAAK,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/providers/firecrawl/adapter.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Firecrawl Provider Adapter (firecrawl tech-plan §1, D3–D6).
+ *
+ * Implements the Firecrawl Provider Descriptor with Search, Reader, Map,
+ * async Crawl, Quota, and Diagnostics capabilities on top of the
+ * direct-HTTP transport (`./client.ts`). The Adapter owns credentials,
+ * transport lifecycle, Provider field mapping, and failure normalization;
+ * shared execution owns cache and retry policy.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import capability types, normalized errors, Provider identity
+ *     types, and the Adapter-local credential and transport Modules.
+ *   - Must NOT import command presentation, output mode, or another
+ *     Provider's Adapter.
+ *
+ * Field mapping (tech-plan D4/D5/D6; investigation §3.1–§3.4):
+ *   Search data[].title       -> title
+ *   Search data[].url         -> url
+ *   Search data[].markdown    -> summary  (high content-size; else description)
+ *   Search data[].description -> summary  (medium content-size fallback)
+ *
+ *   Scrape data.markdown|text -> content
+ *   Scrape data.metadata.sourceURL -> finalUrl
+ *   Scrape data.metadata.title     -> title  (better than Tavily's null)
+ *
+ *   Map links[]               -> urls
+ */
+import type { ProviderDescriptor } from "../types.js";
+import { type AsyncJobStateFile } from "../../lib/async-job-state.js";
+import { type FirecrawlTransportDeps } from "./client.js";
+/**
+ * Dependencies the Firecrawl Adapter accepts. The unified `transport`
+ * seam carries `fetch` and timer injection; `crawlStateFile` is the
+ * async-job-state port the async Crawl Capability uses for
+ * resume-on-restart (tech-plan D2). Production defaults to the on-disk
+ * implementation under `~/.scoutline/crawl/`; tests inject in-memory
+ * doubles to exercise the lifecycle deterministically.
+ */
+export interface FirecrawlAdapterDependencies {
+    readonly transport?: FirecrawlTransportDeps;
+    readonly crawlStateFile?: AsyncJobStateFile;
+    /** Disk dir for the crawl create-lock; defaults to asyncJobStateDir("crawl"). */
+    readonly crawlStateDir?: string;
+}
+/**
+ * Build the Firecrawl Provider Descriptor. Advertises the full Firecrawl
+ * capability set. `create()` wires all six capabilities — Search, Reader,
+ * Map, async Crawl (create→poll→resume + reclaim-on-miss), Quota
+ * (`unit:"credits"`), and Diagnostics (single-scrape probe). Construction
+ * is side-effect-free; the transport is invoked per Capability call.
+ */
+export declare function createFirecrawlDescriptor(dependencies?: FirecrawlAdapterDependencies): ProviderDescriptor;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/providers/firecrawl/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/providers/firecrawl/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH,OAAO,KAAK,EAIV,kBAAkB,EACnB,MAAM,aAAa,CAAC;AA4BrB,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,8BAA8B,CAAC;AAYtC,OAAO,EAYL,KAAK,sBAAsB,EAC5B,MAAM,aAAa,CAAC;AA0hCrB;;;;;;;GAOG;AACH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC;IAC5C,QAAQ,CAAC,cAAc,CAAC,EAAE,iBAAiB,CAAC;IAC5C,iFAAiF;IACjF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,CAAC,EAAE,4BAA4B,GAC1C,kBAAkB,CAoCpB"}