@zenalexa/unicli 0.220.0 → 0.221.0

package/src/adapters/google-patents-web/search.ts

@@ -0,0 +1,196 @@
+/**
+ * @owner       src::adapters::google-patents-web::search
+ * @does        Keyless free-text patent search via the public XHR endpoint that drives patents.google.com — distinct from src/adapters/google-patents-bq which talks to BigQuery and needs a billed GCP project.
+ * @needs       src/adapters/google-patents-web/_shared.ts, src/engine/normalizer/patent-envelope.ts, src/registry.ts
+ * @feeds       src/commands/patent.ts (capability tag patent.search)
+ * @breaks      PATENT_API_DEPRECATED with status code embedded when the XHR returns non-2xx (typically 403 → suspected UA gating); PATENT_NOT_FOUND on empty result; PATENT_SCHEMA_DRIFT when the JSON shape no longer carries results.cluster[].result[]
+ * @invariants  output rows are canonical PatentRecord; source_adapter='google-patents-web'; results are server-ordered (Google's relevance ranking)
+ * @side-effects HTTPS egress to patents.google.com only — no env reads, no cookies, no auth
+ * @perf        single XHR request, ~40-100 KB; results capped at min(limit, 100) per call
+ * @concurrency safe — stateless
+ * @test        verification proof captured in docs/skills/patent-cookbook.md (recipe: day-zero search)
+ * @stability   experimental
+ * @since       2026-05-18
+ * @verification keyless-best-effort — Google does not publish a stability contract for this XHR; we live-call it from the same User-Agent the public site uses
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import { assemblePatentRecord } from "../../engine/normalizer/patent-envelope.js";
+import { buildPatentEnvelope } from "../../engine/normalizer/patent-envelope.js";
+import {
+  GooglePatentsHttpError,
+  buildGooglePatentsXhrUrl,
+  fetchGooglePatentsJson,
+  flattenGoogleXhrResults,
+  projectGoogleRowToRecord,
+  type GoogleXhrResponse,
+} from "./_shared.js";
+
+const ADAPTER_PATH = "src/adapters/google-patents-web/search.ts";
+
+interface SearchArgs {
+  query?: unknown;
+  limit?: unknown;
+  since?: unknown;
+}
+
+function clampLimit(raw: unknown): number {
+  const num = typeof raw === "number" ? raw : Number(raw);
+  if (!Number.isFinite(num) || num <= 0) return 25;
+  return Math.min(100, Math.max(1, Math.floor(num)));
+}
+
+function normaliseSince(raw: unknown): string | undefined {
+  if (typeof raw !== "string") return undefined;
+  const trimmed = raw.trim();
+  return /^\d{4}$/.test(trimmed) ? trimmed : undefined;
+}
+
+export async function runGooglePatentsWebSearch(
+  kwargs: SearchArgs,
+): Promise<unknown[]> {
+  const query = String(kwargs.query ?? "").trim();
+  if (query.length === 0) {
+    return [
+      {
+        envelope: buildPatentEnvelope({
+          code: "PATENT_UNSUPPORTED_QUERY",
+          adapter_path: ADAPTER_PATH,
+          step: "validate",
+          suggestion: "google-patents-web search requires a non-empty query",
+          alternatives: ["freepatentsonline-web"],
+        }),
+      },
+    ];
+  }
+  const limit = clampLimit(kwargs.limit);
+  const since = normaliseSince(kwargs.since);
+  const url = buildGooglePatentsXhrUrl(query, limit, since);
+
+  let body: GoogleXhrResponse;
+  try {
+    body = await fetchGooglePatentsJson<GoogleXhrResponse>(url);
+  } catch (err) {
+    if (err instanceof GooglePatentsHttpError) {
+      return [
+        {
+          envelope: buildPatentEnvelope({
+            code:
+              err.status === 429
+                ? "PATENT_RATE_LIMIT"
+                : err.status === 403
+                  ? "PATENT_REGION_BLOCKED"
+                  : "PATENT_API_DEPRECATED",
+            adapter_path: ADAPTER_PATH,
+            step: "fetch",
+            suggestion: `Google Patents XHR returned HTTP ${err.status} for ${err.url}; retry with --sources freepatentsonline-web, or check if Google now requires a session cookie`,
+            alternatives: ["freepatentsonline-web", "espacenet"],
+            retryable: err.status === 429,
+          }),
+        },
+      ];
+    }
+    throw err;
+  }
+
+  const rows = flattenGoogleXhrResults(body);
+  if (rows.length === 0) {
+    if (!body.results || !Array.isArray(body.results.cluster)) {
+      return [
+        {
+          envelope: buildPatentEnvelope({
+            code: "PATENT_SCHEMA_DRIFT",
+            adapter_path: ADAPTER_PATH,
+            step: "select",
+            suggestion:
+              "Google Patents XHR no longer carries results.cluster[].result[]; the adapter's flattenGoogleXhrResults projection needs updating",
+            alternatives: ["freepatentsonline-web"],
+          }),
+        },
+      ];
+    }
+    return [
+      {
+        envelope: buildPatentEnvelope({
+          code: "PATENT_NOT_FOUND",
+          adapter_path: ADAPTER_PATH,
+          step: "select",
+          suggestion: `google-patents-web returned no rows for "${query}"`,
+          alternatives: ["freepatentsonline-web", "espacenet"],
+        }),
+      },
+    ];
+  }
+
+  const out: unknown[] = [];
+  for (const row of rows.slice(0, limit)) {
+    const partial = projectGoogleRowToRecord(row, url);
+    if (!partial.publication_number) continue;
+    try {
+      out.push(
+        assemblePatentRecord(
+          partial as Parameters<typeof assemblePatentRecord>[0],
+        ),
+      );
+    } catch {
+      // Rows whose publication_number cannot be canonicalised are skipped
+      // rather than synthesised — we never invent ST.16 fields.
+    }
+  }
+  if (out.length === 0) {
+    return [
+      {
+        envelope: buildPatentEnvelope({
+          code: "PATENT_NOT_FOUND",
+          adapter_path: ADAPTER_PATH,
+          step: "normalize",
+          suggestion: `google-patents-web returned ${rows.length} rows but none carried a canonicalisable publication_number`,
+          alternatives: ["freepatentsonline-web", "espacenet"],
+        }),
+      },
+    ];
+  }
+  return out;
+}
+
+cli({
+  site: "google-patents-web",
+  name: "search",
+  description:
+    "Keyless Google Patents search via the public XHR endpoint (no API key, no Chrome required)",
+  domain: "patents.google.com",
+  strategy: Strategy.PUBLIC,
+  adapter_path: ADAPTER_PATH,
+  args: [
+    {
+      name: "query",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Free-text query (Google Patents smart-search syntax)",
+    },
+    {
+      name: "limit",
+      type: "int",
+      default: 25,
+      description: "Max results to return (1-100)",
+    },
+    {
+      name: "since",
+      type: "str",
+      description:
+        "Earliest publication year (YYYY); translated to after:publication:YYYY0101",
+    },
+  ],
+  columns: [
+    "publication_number",
+    "title",
+    "publication_date",
+    "assignees",
+    "source_url",
+  ],
+  capabilities: ["http.fetch", "patent.search"],
+  minimum_capability: "http.fetch",
+  func: async (_page, kwargs) =>
+    runGooglePatentsWebSearch(kwargs as SearchArgs),
+});

package/src/adapters/inpi-br/_shared.ts

@@ -0,0 +1,98 @@
+/**
+ * @owner       src::adapters::inpi-br::_shared
+ * @does        Shared helpers for the INPI Brasil browser adapter — busca.inpi.gov.br/pePI/ has no programmatic API today (pre-API status); the browser route is the only path.
+ * @needs       src/engine/transport/mcp-browser.ts, src/engine/normalizer/patent-envelope.ts, src/types/patent.ts
+ * @feeds       src/adapters/inpi-br/*.ts
+ * @breaks      none — pure helpers
+ * @invariants  every transport gap surfaces as a PatentEnvelope row
+ * @side-effects none
+ * @perf        n/a
+ * @concurrency safe
+ * @test        covered transitively
+ * @stability   experimental
+ * @since       2026-05-18
+ * @verification browser-only
+ */
+
+import {
+  TransportError,
+  initMcpBrowserTransport,
+  mcpBrowserEvaluate,
+  mcpBrowserNavigate,
+  type McpBrowserResult,
+} from "../../engine/transport/mcp-browser.js";
+import { buildPatentEnvelope } from "../../engine/normalizer/patent-envelope.js";
+import type { PatentEnvelope, PatentErrorCode } from "../../types/patent.js";
+
+export function inpiBrEnvelope(
+  code: PatentErrorCode,
+  adapter_path: string,
+  step: string,
+  suggestion: string,
+  alternatives: string[] = [],
+): PatentEnvelope {
+  return buildPatentEnvelope({
+    code,
+    adapter_path,
+    step,
+    suggestion,
+    alternatives,
+    retryable: false,
+  });
+}
+
+export function transportErrorToInpiBrEnvelope(
+  err: TransportError,
+  adapter_path: string,
+  step: string,
+): PatentEnvelope {
+  if (err.code === "MCP_BUS_MISSING") {
+    return buildPatentEnvelope({
+      code: "PATENT_API_DEPRECATED",
+      adapter_path,
+      step,
+      suggestion:
+        "engine has no outbound MCP transport wired into the bus today; INPI Brasil has no upstream API so the browser path is the only route — install an McpResolver to activate this adapter",
+      alternatives: ["espacenet", "lens"],
+      retryable: false,
+    });
+  }
+  return buildPatentEnvelope({
+    code: "PATENT_API_DEPRECATED",
+    adapter_path,
+    step,
+    suggestion: `mcp-browser transport error (${err.code}): ${err.message}`,
+    alternatives: ["espacenet"],
+    retryable: false,
+  });
+}
+
+export async function inpiBrNavigateAndExtract<T>(
+  url: string,
+  expression: string,
+): Promise<McpBrowserResult<T>> {
+  const init = await initMcpBrowserTransport();
+  if (init.active_server === "none") {
+    const code =
+      init.reason === "bus-missing" ? "MCP_BUS_MISSING" : "MCP_NO_SERVER";
+    throw new TransportError(code, `mcp-browser unavailable (${init.reason})`);
+  }
+  const navResult = await mcpBrowserNavigate({ url });
+  if (!navResult.ok) {
+    throw new TransportError(
+      navResult.code ?? "MCP_NAVIGATE_FAILED",
+      navResult.message ?? "navigate did not succeed",
+    );
+  }
+  const evalResult = await mcpBrowserEvaluate<T>({
+    expression,
+    tab: navResult.tab,
+  });
+  if (!evalResult.ok) {
+    throw new TransportError(
+      evalResult.code ?? "MCP_EVALUATE_FAILED",
+      evalResult.message ?? "evaluate did not succeed",
+    );
+  }
+  return evalResult;
+}

package/src/adapters/inpi-br/get.ts

@@ -0,0 +1,193 @@
+/**
+ * @owner       src::adapters::inpi-br::get
+ * @does        Browser-driven retrieval of an INPI Brasil patent record by application/publication number; extracts the bibliographic block from the pePI detail page.
+ * @needs       src/engine/transport/mcp-browser.ts, src/engine/normalizer/patent-envelope.ts, src/adapters/inpi-br/_shared.ts, src/registry.ts
+ * @feeds       src/commands/patent.ts (capability tag patent.get)
+ * @breaks      PATENT_INVALID_NUMBER, PATENT_NOT_FOUND, PATENT_API_DEPRECATED (MCP_BUS_MISSING)
+ * @invariants  output row is a canonical PatentRecord
+ * @side-effects controls Chrome via MCP
+ * @perf        single navigate + evaluate
+ * @concurrency safe
+ * @test        tests/unit/adapters/inpi-br/search.test.ts (shared transport-error path)
+ * @stability   experimental
+ * @since       2026-05-18
+ * @verification browser-only
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import { TransportError } from "../../engine/transport/mcp-browser.js";
+import { assemblePatentRecord } from "../../engine/normalizer/patent-envelope.js";
+import {
+  inpiBrEnvelope,
+  inpiBrNavigateAndExtract,
+  transportErrorToInpiBrEnvelope,
+} from "./_shared.js";
+
+const ADAPTER_PATH = "src/adapters/inpi-br/get.ts";
+
+interface InpiBrDetail {
+  publication_number?: string;
+  application_number?: string;
+  title?: string;
+  abstract?: string;
+  applicant?: string;
+  inventor?: string;
+  publication_date?: string;
+  filing_date?: string;
+  source_url?: string;
+}
+
+const DETAIL_EXTRACTOR = `(() => {
+  const text = (sel) => {
+    const node = document.querySelector(sel);
+    return node ? (node.textContent || '').trim() : '';
+  };
+  return {
+    publication_number: text('[data-field="numPedido"], .num-pedido, td.numero'),
+    application_number: text('[data-field="numAplicacao"], .num-aplicacao'),
+    title: text('[data-field="titulo"], .titulo, h1'),
+    abstract: text('[data-field="resumo"], .resumo'),
+    applicant: text('[data-field="depositante"], .depositante'),
+    inventor: text('[data-field="inventor"], .inventor'),
+    publication_date: text('[data-field="dataPub"], .data-pub'),
+    filing_date: text('[data-field="dataDep"], .data-dep'),
+    source_url: location.href,
+  };
+})()`;
+
+function detailUrlFor(pubNo: string): string {
+  const stripped = pubNo.replace(/^BR[-]?/, "");
+  const params = new URLSearchParams({
+    Action: "detail",
+    NumPedido: stripped,
+  });
+  return `https://busca.inpi.gov.br/pePI/servlet/PatenteServletController?${params.toString()}`;
+}
+
+export async function runInpiBrGet(kwargs: {
+  publication_number: string;
+}): Promise<unknown[]> {
+  const pubNo = String(kwargs.publication_number ?? "").trim();
+  if (pubNo.length === 0) {
+    return [
+      {
+        envelope: inpiBrEnvelope(
+          "PATENT_INVALID_NUMBER",
+          ADAPTER_PATH,
+          "validate",
+          "inpi-br get requires a non-empty publication_number",
+        ),
+      },
+    ];
+  }
+  const url = detailUrlFor(pubNo);
+  let detail: InpiBrDetail;
+  try {
+    const result = await inpiBrNavigateAndExtract<InpiBrDetail>(
+      url,
+      DETAIL_EXTRACTOR,
+    );
+    if (!result.data) {
+      return [
+        {
+          envelope: inpiBrEnvelope(
+            "PATENT_SCHEMA_DRIFT",
+            ADAPTER_PATH,
+            "evaluate",
+            "inpi-br detail evaluate returned no data",
+          ),
+        },
+      ];
+    }
+    detail = result.data;
+  } catch (err) {
+    if (err instanceof TransportError) {
+      return [
+        {
+          envelope: transportErrorToInpiBrEnvelope(
+            err,
+            ADAPTER_PATH,
+            "navigate",
+          ),
+        },
+      ];
+    }
+    throw err;
+  }
+  if (!detail.publication_number && !detail.title) {
+    return [
+      {
+        envelope: inpiBrEnvelope(
+          "PATENT_NOT_FOUND",
+          ADAPTER_PATH,
+          "evaluate",
+          `inpi-br detail page for "${pubNo}" yielded no bibliographic fields`,
+          ["espacenet"],
+        ),
+      },
+    ];
+  }
+  const rawPubNo = detail.publication_number || pubNo;
+  const canonicalPubNo = /^BR[-]?/.test(rawPubNo) ? rawPubNo : `BR${rawPubNo}`;
+  try {
+    return [
+      assemblePatentRecord({
+        publication_number: canonicalPubNo,
+        application_number: detail.application_number || undefined,
+        title: detail.title || undefined,
+        abstract: detail.abstract || undefined,
+        assignees: detail.applicant
+          ? [{ name: detail.applicant, country: "BR" }]
+          : undefined,
+        inventors: detail.inventor
+          ? [{ name: detail.inventor, country: "BR" }]
+          : undefined,
+        publication_date: detail.publication_date || undefined,
+        filing_date: detail.filing_date || undefined,
+        source_adapter: "inpi-br",
+        source_url: detail.source_url || url,
+      } as Parameters<typeof assemblePatentRecord>[0]),
+    ];
+  } catch {
+    return [
+      {
+        envelope: inpiBrEnvelope(
+          "PATENT_NOT_FOUND",
+          ADAPTER_PATH,
+          "normalize",
+          `inpi-br detail page for "${pubNo}" did not yield a valid publication_number`,
+          ["espacenet"],
+        ),
+      },
+    ];
+  }
+}
+
+cli({
+  site: "inpi-br",
+  name: "get",
+  description: "Retrieve a single INPI Brasil patent record (browser-only)",
+  domain: "busca.inpi.gov.br",
+  strategy: Strategy.PUBLIC,
+  adapter_path: ADAPTER_PATH,
+  args: [
+    {
+      name: "publication_number",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Brazil patent application/publication number",
+    },
+  ],
+  columns: [
+    "publication_number",
+    "title",
+    "publication_date",
+    "filing_date",
+    "source_url",
+  ],
+  capabilities: ["mcp-browser.navigate", "mcp-browser.evaluate", "patent.get"],
+  minimum_capability: "mcp-browser.evaluate",
+  func: async (_page, kwargs) =>
+    runInpiBrGet(kwargs as { publication_number: string }),
+});

package/src/adapters/inpi-br/search.ts

@@ -0,0 +1,206 @@
+/**
+ * @owner       src::adapters::inpi-br::search
+ * @does        Browser-driven INPI Brasil search at busca.inpi.gov.br/pePI/ — Brazil's patent office has no open API (pre-API status); the public web search is the only programmatic surface.
+ * @needs       src/engine/transport/mcp-browser.ts, src/engine/normalizer/patent-envelope.ts, src/adapters/inpi-br/_shared.ts, src/registry.ts
+ * @feeds       src/commands/patent.ts (capability tag patent.search)
+ * @breaks      PATENT_UNSUPPORTED_QUERY (empty), PATENT_NOT_FOUND (no rows), PATENT_API_DEPRECATED with MCP_BUS_MISSING
+ * @invariants  output rows canonicalized into PatentRecord with source_adapter='inpi-br'
+ * @side-effects controls Chrome via MCP
+ * @perf        single navigate + evaluate
+ * @concurrency safe
+ * @test        tests/unit/adapters/inpi-br/search.test.ts
+ * @stability   experimental
+ * @since       2026-05-18
+ * @verification browser-only
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import { TransportError } from "../../engine/transport/mcp-browser.js";
+import { assemblePatentRecord } from "../../engine/normalizer/patent-envelope.js";
+import {
+  inpiBrEnvelope,
+  inpiBrNavigateAndExtract,
+  transportErrorToInpiBrEnvelope,
+} from "./_shared.js";
+
+const ADAPTER_PATH = "src/adapters/inpi-br/search.ts";
+const INPI_BR_SEARCH_URL =
+  "https://busca.inpi.gov.br/pePI/servlet/PatenteServletController";
+
+interface InpiBrRow {
+  publication_number: string;
+  title?: string;
+  applicant?: string;
+  publication_date?: string;
+  filing_date?: string;
+  source_url?: string;
+}
+
+const EXTRACTOR = `(() => {
+  const rows = Array.from(
+    document.querySelectorAll('table.tabela tr.linha, table tr[bgcolor]')
+  ).map((el) => {
+    const text = (sel) => {
+      const node = el.querySelector(sel);
+      return node ? (node.textContent || '').trim() : '';
+    };
+    const cells = Array.from(el.querySelectorAll('td')).map((td) => (td.textContent || '').trim());
+    const linkEl = el.querySelector('a[href]');
+    return {
+      publication_number: text('td.num-pedido, td:first-child') || (cells[0] || ''),
+      title: text('td.titulo, td:nth-child(3)') || (cells[2] || ''),
+      applicant: text('td.depositante, td:nth-child(4)') || (cells[3] || ''),
+      publication_date: text('td.data-pub, td:nth-child(5)') || (cells[4] || ''),
+      filing_date: text('td.data-dep, td:nth-child(2)') || (cells[1] || ''),
+      source_url: linkEl ? linkEl.href : '',
+    };
+  });
+  return { rows };
+})()`;
+
+function buildSearchUrl(query: string): string {
+  const params = new URLSearchParams({
+    Action: "searchPatente",
+    ExpressaoPesquisa: query,
+  });
+  return `${INPI_BR_SEARCH_URL}?${params.toString()}`;
+}
+
+export async function runInpiBrSearch(kwargs: {
+  query: string;
+  limit?: number;
+}): Promise<unknown[]> {
+  const limit =
+    typeof kwargs.limit === "number" && Number.isFinite(kwargs.limit)
+      ? Math.max(1, Math.min(100, Math.floor(kwargs.limit)))
+      : 25;
+  const query = String(kwargs.query ?? "").trim();
+  if (query.length === 0) {
+    return [
+      {
+        envelope: inpiBrEnvelope(
+          "PATENT_UNSUPPORTED_QUERY",
+          ADAPTER_PATH,
+          "validate",
+          "inpi-br search requires a non-empty query",
+        ),
+      },
+    ];
+  }
+  const url = buildSearchUrl(query);
+  let extract: { rows: InpiBrRow[] };
+  try {
+    const result = await inpiBrNavigateAndExtract<{ rows: InpiBrRow[] }>(
+      url,
+      EXTRACTOR,
+    );
+    if (!result.data) {
+      return [
+        {
+          envelope: inpiBrEnvelope(
+            "PATENT_SCHEMA_DRIFT",
+            ADAPTER_PATH,
+            "evaluate",
+            "inpi-br evaluate returned no data; selectors likely drifted",
+          ),
+        },
+      ];
+    }
+    extract = result.data;
+  } catch (err) {
+    if (err instanceof TransportError) {
+      return [
+        {
+          envelope: transportErrorToInpiBrEnvelope(
+            err,
+            ADAPTER_PATH,
+            "navigate",
+          ),
+        },
+      ];
+    }
+    throw err;
+  }
+  if (extract.rows.length === 0) {
+    return [
+      {
+        envelope: inpiBrEnvelope(
+          "PATENT_NOT_FOUND",
+          ADAPTER_PATH,
+          "evaluate",
+          `inpi-br returned no rows for query "${query}"`,
+          ["espacenet", "lens"],
+        ),
+      },
+    ];
+  }
+  const out: unknown[] = [];
+  for (const row of extract.rows.slice(0, limit)) {
+    if (!row.publication_number) continue;
+    const normalizedPub = /^BR[-]?/.test(row.publication_number)
+      ? row.publication_number
+      : `BR${row.publication_number}`;
+    try {
+      out.push(
+        assemblePatentRecord({
+          publication_number: normalizedPub,
+          title: row.title || undefined,
+          assignees: row.applicant
+            ? [{ name: row.applicant, country: "BR" }]
+            : undefined,
+          publication_date: row.publication_date || undefined,
+          filing_date: row.filing_date || undefined,
+          source_adapter: "inpi-br",
+          source_url: row.source_url || url,
+        } as Parameters<typeof assemblePatentRecord>[0]),
+      );
+    } catch {
+      // Skip malformed rows.
+    }
+  }
+  if (out.length === 0) {
+    out.push({
+      envelope: inpiBrEnvelope(
+        "PATENT_NOT_FOUND",
+        ADAPTER_PATH,
+        "normalize",
+        "inpi-br returned rows but none normalized to a valid publication_number",
+        ["espacenet"],
+      ),
+    });
+  }
+  return out;
+}
+
+cli({
+  site: "inpi-br",
+  name: "search",
+  description: "Search INPI Brasil patents (browser-only, no upstream API)",
+  domain: "busca.inpi.gov.br",
+  strategy: Strategy.PUBLIC,
+  adapter_path: ADAPTER_PATH,
+  args: [
+    {
+      name: "query",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Free-text query for INPI Brasil patent search",
+    },
+    {
+      name: "limit",
+      type: "int",
+      default: 25,
+      description: "Max results (1-100)",
+    },
+  ],
+  columns: ["publication_number", "title", "publication_date", "source_url"],
+  capabilities: [
+    "mcp-browser.navigate",
+    "mcp-browser.evaluate",
+    "patent.search",
+  ],
+  minimum_capability: "mcp-browser.evaluate",
+  func: async (_page, kwargs) =>
+    runInpiBrSearch(kwargs as { query: string; limit?: number }),
+});