@zenalexa/unicli 0.220.0 → 0.221.0

package/src/adapters/espacenet/get.ts

@@ -0,0 +1,185 @@
+/**
+ * @owner       src::adapters::espacenet::get
+ * @does        Browser-driven retrieval of a single Espacenet publication detail page; extracts bibliographic fields and emits a PatentRecord.
+ * @needs       src/engine/transport/mcp-browser.ts, src/engine/normalizer/patent-envelope.ts, src/adapters/espacenet/_shared.ts, src/registry.ts
+ * @feeds       src/commands/patent.ts (capability tag patent.get)
+ * @breaks      PATENT_INVALID_NUMBER, PATENT_NOT_FOUND, PATENT_API_DEPRECATED with MCP_BUS_MISSING
+ * @invariants  output is a single PatentRecord row when upstream answers; never returns a stub
+ * @side-effects controls Chrome via MCP
+ * @perf        single navigate + evaluate
+ * @concurrency safe
+ * @test        tests/unit/adapters/espacenet/search.test.ts (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 {
+  espacenetEnvelope,
+  espacenetNavigateAndExtract,
+  transportErrorToEspacenetEnvelope,
+} from "./_shared.js";
+
+const ADAPTER_PATH = "src/adapters/espacenet/get.ts";
+
+interface EspacenetDetail {
+  publication_number?: string;
+  application_number?: string;
+  title?: string;
+  abstract?: string;
+  applicant?: string;
+  inventor?: string;
+  publication_date?: string;
+  filing_date?: string;
+  source_url?: string;
+  html_marker?: string;
+}
+
+const DETAIL_EXTRACTOR = `(() => {
+  const text = (sel) => {
+    const node = document.querySelector(sel);
+    return node ? (node.textContent || '').trim() : '';
+  };
+  return {
+    publication_number: text('[data-test="publication-number"], .publicationNumber'),
+    application_number: text('[data-test="application-number"], .applicationNumber'),
+    title: text('[data-test="title"], h1.title, .invention-title'),
+    abstract: text('[data-test="abstract"], .abstract'),
+    applicant: text('[data-test="applicant"], .applicantName'),
+    inventor: text('[data-test="inventor"], .inventorName'),
+    publication_date: text('[data-test="publication-date"], .publicationDate'),
+    filing_date: text('[data-test="filing-date"], .filingDate'),
+    source_url: location.href,
+    html_marker: document.body && document.body.innerText
+      ? document.body.innerText.slice(0, 200)
+      : '',
+  };
+})()`;
+
+function detailUrlFor(pubNo: string): string {
+  return `https://worldwide.espacenet.com/patent/search/publication/${encodeURIComponent(pubNo)}`;
+}
+
+export async function runEspacenetGet(kwargs: {
+  publication_number: string;
+}): Promise<unknown[]> {
+  const pubNo = String(kwargs.publication_number ?? "").trim();
+  if (pubNo.length === 0) {
+    return [
+      {
+        envelope: espacenetEnvelope(
+          "PATENT_INVALID_NUMBER",
+          ADAPTER_PATH,
+          "validate",
+          "espacenet get requires a non-empty publication_number",
+        ),
+      },
+    ];
+  }
+  const url = detailUrlFor(pubNo);
+  let detail: EspacenetDetail;
+  try {
+    const result = await espacenetNavigateAndExtract<EspacenetDetail>(
+      url,
+      DETAIL_EXTRACTOR,
+    );
+    if (!result.data) {
+      return [
+        {
+          envelope: espacenetEnvelope(
+            "PATENT_SCHEMA_DRIFT",
+            ADAPTER_PATH,
+            "evaluate",
+            "espacenet detail evaluate returned no data",
+          ),
+        },
+      ];
+    }
+    detail = result.data;
+  } catch (err) {
+    if (err instanceof TransportError) {
+      return [
+        {
+          envelope: transportErrorToEspacenetEnvelope(
+            err,
+            ADAPTER_PATH,
+            "navigate",
+          ),
+        },
+      ];
+    }
+    throw err;
+  }
+  const fieldCount = [detail.publication_number, detail.title].filter(
+    Boolean,
+  ).length;
+  if (fieldCount === 0) {
+    return [
+      {
+        envelope: espacenetEnvelope(
+          "PATENT_NOT_FOUND",
+          ADAPTER_PATH,
+          "evaluate",
+          `espacenet detail page for "${pubNo}" yielded no bibliographic fields`,
+          ["epo", "uspto"],
+        ),
+      },
+    ];
+  }
+  const canonicalPubNo = detail.publication_number || pubNo;
+  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 }] : undefined,
+        inventors: detail.inventor ? [{ name: detail.inventor }] : undefined,
+        publication_date: detail.publication_date || undefined,
+        filing_date: detail.filing_date || undefined,
+        source_adapter: "espacenet",
+        source_url: detail.source_url || url,
+      } as Parameters<typeof assemblePatentRecord>[0]),
+    ];
+  } catch {
+    return [
+      {
+        envelope: espacenetEnvelope(
+          "PATENT_NOT_FOUND",
+          ADAPTER_PATH,
+          "normalize",
+          `espacenet detail page for "${pubNo}" did not yield a valid publication_number`,
+          ["epo"],
+        ),
+      },
+    ];
+  }
+}
+
+cli({
+  site: "espacenet",
+  name: "get",
+  description:
+    "Retrieve a single Espacenet publication detail (browser, no key)",
+  domain: "worldwide.espacenet.com",
+  strategy: Strategy.PUBLIC,
+  adapter_path: ADAPTER_PATH,
+  args: [
+    {
+      name: "publication_number",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "ST.16 publication number (e.g. EP4123456A1)",
+    },
+  ],
+  columns: ["publication_number", "title", "publication_date", "source_url"],
+  capabilities: ["mcp-browser.navigate", "mcp-browser.evaluate", "patent.get"],
+  minimum_capability: "mcp-browser.evaluate",
+  func: async (_page, kwargs) =>
+    runEspacenetGet(kwargs as { publication_number: string }),
+});

package/src/adapters/espacenet/legal-status.ts

@@ -0,0 +1,151 @@
+/**
+ * @owner       src::adapters::espacenet::legal-status
+ * @does        Browser-driven Espacenet legal-status lookup — INPADOC events table on the legal-status tab.
+ * @needs       src/engine/transport/mcp-browser.ts, src/adapters/espacenet/_shared.ts, src/registry.ts
+ * @feeds       src/commands/patent.ts (capability tag patent.legal-status)
+ * @breaks      PATENT_INVALID_NUMBER, PATENT_NOT_FOUND, PATENT_API_DEPRECATED (MCP_BUS_MISSING)
+ * @invariants  output row carries legal_status as the most-recent INPADOC event verbatim
+ * @side-effects controls Chrome via MCP
+ * @perf        single navigate + evaluate
+ * @concurrency safe
+ * @test        tests/unit/adapters/espacenet/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 {
+  espacenetEnvelope,
+  espacenetNavigateAndExtract,
+  transportErrorToEspacenetEnvelope,
+} from "./_shared.js";
+
+const ADAPTER_PATH = "src/adapters/espacenet/legal-status.ts";
+
+interface EspacenetLegalExtract {
+  publication_number?: string;
+  legal_status?: string;
+  status_date?: string;
+  source_url?: string;
+}
+
+const EXTRACTOR = `(() => {
+  const text = (sel) => {
+    const node = document.querySelector(sel);
+    return node ? (node.textContent || '').trim() : '';
+  };
+  return {
+    publication_number: text('[data-test="publication-number"], .publicationNumber'),
+    legal_status: text('[data-test="legal-status"] tr:first-child td:nth-child(2), .legalStatus__currentStatus'),
+    status_date: text('[data-test="legal-status"] tr:first-child td:nth-child(1), .legalStatus__currentDate'),
+    source_url: location.href,
+  };
+})()`;
+
+function legalUrlFor(pubNo: string): string {
+  return `https://worldwide.espacenet.com/patent/search/legal-status/${encodeURIComponent(pubNo)}`;
+}
+
+export async function runEspacenetLegalStatus(kwargs: {
+  publication_number: string;
+}): Promise<unknown[]> {
+  const pubNo = String(kwargs.publication_number ?? "").trim();
+  if (pubNo.length === 0) {
+    return [
+      {
+        envelope: espacenetEnvelope(
+          "PATENT_INVALID_NUMBER",
+          ADAPTER_PATH,
+          "validate",
+          "espacenet legal-status requires a non-empty publication_number",
+        ),
+      },
+    ];
+  }
+  const url = legalUrlFor(pubNo);
+  let detail: EspacenetLegalExtract;
+  try {
+    const result = await espacenetNavigateAndExtract<EspacenetLegalExtract>(
+      url,
+      EXTRACTOR,
+    );
+    if (!result.data) {
+      return [
+        {
+          envelope: espacenetEnvelope(
+            "PATENT_SCHEMA_DRIFT",
+            ADAPTER_PATH,
+            "evaluate",
+            "espacenet legal-status evaluate returned no data",
+          ),
+        },
+      ];
+    }
+    detail = result.data;
+  } catch (err) {
+    if (err instanceof TransportError) {
+      return [
+        {
+          envelope: transportErrorToEspacenetEnvelope(
+            err,
+            ADAPTER_PATH,
+            "navigate",
+          ),
+        },
+      ];
+    }
+    throw err;
+  }
+  if (!detail.legal_status) {
+    return [
+      {
+        envelope: espacenetEnvelope(
+          "PATENT_NOT_FOUND",
+          ADAPTER_PATH,
+          "evaluate",
+          `espacenet returned no legal_status for "${pubNo}"`,
+          ["epo"],
+        ),
+      },
+    ];
+  }
+  return [
+    {
+      publication_number: detail.publication_number || pubNo,
+      legal_status: detail.legal_status,
+      status_date: detail.status_date,
+      source_adapter: "espacenet",
+      source_url: detail.source_url || url,
+      retrieved_at: new Date().toISOString(),
+    },
+  ];
+}
+
+cli({
+  site: "espacenet",
+  name: "legal-status",
+  description: "Espacenet INPADOC legal-status lookup (browser)",
+  domain: "worldwide.espacenet.com",
+  strategy: Strategy.PUBLIC,
+  adapter_path: ADAPTER_PATH,
+  args: [
+    {
+      name: "publication_number",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "ST.16 publication number",
+    },
+  ],
+  columns: ["publication_number", "legal_status", "status_date", "source_url"],
+  capabilities: [
+    "mcp-browser.navigate",
+    "mcp-browser.evaluate",
+    "patent.legal-status",
+  ],
+  minimum_capability: "mcp-browser.evaluate",
+  func: async (_page, kwargs) =>
+    runEspacenetLegalStatus(kwargs as { publication_number: string }),
+});

package/src/adapters/espacenet/search.ts

@@ -0,0 +1,229 @@
+/**
+ * @owner       src::adapters::espacenet::search
+ * @does        Browser-driven Espacenet front-end search at worldwide.espacenet.com/patent/search — the EPO public no-key fallback for global patent search; complements the keyed EPO OPS adapter at src/adapters/epo/*.
+ * @needs       src/engine/transport/mcp-browser.ts, src/engine/normalizer/patent-envelope.ts, src/adapters/espacenet/_shared.ts, src/registry.ts
+ * @feeds       src/commands/patent.ts (capability tag patent.search)
+ * @breaks      PATENT_API_DEPRECATED with MCP_BUS_MISSING when no outbound MCP transport; PATENT_NOT_FOUND on empty result; PATENT_BROWSER_CAPTCHA on EPO's anti-bot challenge
+ * @invariants  output rows are canonical PatentRecord; source_adapter='espacenet'
+ * @side-effects controls Chrome via MCP
+ * @perf        single navigate + evaluate
+ * @concurrency safe
+ * @test        tests/unit/adapters/espacenet/search.test.ts
+ * @stability   experimental
+ * @since       2026-05-18
+ * @verification browser-only (distinct from EPO OPS which is keyed REST)
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import { TransportError } from "../../engine/transport/mcp-browser.js";
+import { assemblePatentRecord } from "../../engine/normalizer/patent-envelope.js";
+import {
+  espacenetEnvelope,
+  espacenetNavigateAndExtract,
+  transportErrorToEspacenetEnvelope,
+} from "./_shared.js";
+
+const ADAPTER_PATH = "src/adapters/espacenet/search.ts";
+const ESPACENET_SEARCH_URL = "https://worldwide.espacenet.com/patent/search";
+
+interface EspacenetRow {
+  publication_number: string;
+  title?: string;
+  applicant?: string;
+  inventor?: string;
+  publication_date?: string;
+  source_url?: string;
+}
+
+const EXTRACTOR = `(() => {
+  const rows = Array.from(
+    document.querySelectorAll('article.publication, .item--ezfpdY, [data-test="result"]')
+  ).map((el) => {
+    const text = (sel) => {
+      const node = el.querySelector(sel);
+      return node ? (node.textContent || '').trim() : '';
+    };
+    const linkEl = el.querySelector('a[href*="/patent/search/family"], a[href*="/patent/search/publication"], a[href]');
+    return {
+      publication_number: text('[data-test="publication-number"], .publicationNumber, .publication__id'),
+      title: text('[data-test="title"], .publicationTitle, h3'),
+      applicant: text('[data-test="applicant"], .applicantName'),
+      inventor: text('[data-test="inventor"], .inventorName'),
+      publication_date: text('[data-test="publication-date"], .publicationDate, .publication__date'),
+      source_url: linkEl ? linkEl.href : '',
+    };
+  });
+  const html_marker = (document.body && document.body.innerText
+    ? document.body.innerText.slice(0, 200)
+    : '');
+  return { rows, html_marker };
+})()`;
+
+interface EspacenetExtractResult {
+  rows: EspacenetRow[];
+  html_marker?: string;
+}
+
+function buildSearchUrl(query: string, limit: number): string {
+  // Espacenet smart-search query — `q` is the CQL-lite syntax accepted by
+  // the front-end search box. Limit is enforced client-side; Espacenet
+  // paginates server-side via the `?p=` page parameter.
+  const params = new URLSearchParams({ q: query });
+  // Espacenet shows ~25 rows per page; cap requested limit at one page so
+  // the browser does not paginate by default.
+  if (limit > 25) params.set("ps", String(Math.min(100, limit)));
+  return `${ESPACENET_SEARCH_URL}?${params.toString()}`;
+}
+
+export async function runEspacenetSearch(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: espacenetEnvelope(
+          "PATENT_UNSUPPORTED_QUERY",
+          ADAPTER_PATH,
+          "validate",
+          "espacenet search requires a non-empty query",
+        ),
+      },
+    ];
+  }
+  const url = buildSearchUrl(query, limit);
+  let extract: EspacenetExtractResult;
+  try {
+    const result = await espacenetNavigateAndExtract<EspacenetExtractResult>(
+      url,
+      EXTRACTOR,
+    );
+    if (!result.data) {
+      return [
+        {
+          envelope: espacenetEnvelope(
+            "PATENT_SCHEMA_DRIFT",
+            ADAPTER_PATH,
+            "evaluate",
+            "espacenet evaluate returned no data; selector schema likely changed",
+          ),
+        },
+      ];
+    }
+    extract = result.data;
+  } catch (err) {
+    if (err instanceof TransportError) {
+      return [
+        {
+          envelope: transportErrorToEspacenetEnvelope(
+            err,
+            ADAPTER_PATH,
+            "navigate",
+          ),
+        },
+      ];
+    }
+    throw err;
+  }
+  if (extract.rows.length === 0) {
+    const marker = (extract.html_marker ?? "").toLowerCase();
+    if (
+      marker.includes("captcha") ||
+      marker.includes("challenge") ||
+      marker.includes("are you a human")
+    ) {
+      return [
+        {
+          envelope: espacenetEnvelope(
+            "PATENT_BROWSER_CAPTCHA",
+            ADAPTER_PATH,
+            "evaluate",
+            "espacenet served an anti-bot challenge; solve it in the open browser tab and re-run",
+            ["epo"],
+          ),
+        },
+      ];
+    }
+    return [
+      {
+        envelope: espacenetEnvelope(
+          "PATENT_NOT_FOUND",
+          ADAPTER_PATH,
+          "evaluate",
+          `espacenet returned no rows for query "${query}"`,
+          ["epo", "uspto"],
+        ),
+      },
+    ];
+  }
+  const out: unknown[] = [];
+  for (const row of extract.rows.slice(0, limit)) {
+    if (!row.publication_number) continue;
+    try {
+      out.push(
+        assemblePatentRecord({
+          publication_number: row.publication_number,
+          title: row.title || undefined,
+          assignees: row.applicant ? [{ name: row.applicant }] : undefined,
+          inventors: row.inventor ? [{ name: row.inventor }] : undefined,
+          publication_date: row.publication_date || undefined,
+          source_adapter: "espacenet",
+          source_url: row.source_url || url,
+        } as Parameters<typeof assemblePatentRecord>[0]),
+      );
+    } catch {
+      // Skip rows that fail canonicalization rather than synthesize.
+    }
+  }
+  if (out.length === 0) {
+    out.push({
+      envelope: espacenetEnvelope(
+        "PATENT_NOT_FOUND",
+        ADAPTER_PATH,
+        "normalize",
+        "espacenet returned rows but none carried a valid publication_number",
+        ["epo"],
+      ),
+    });
+  }
+  return out;
+}
+
+cli({
+  site: "espacenet",
+  name: "search",
+  description:
+    "Search Espacenet (EPO public no-key front end) for worldwide patents",
+  domain: "worldwide.espacenet.com",
+  strategy: Strategy.PUBLIC,
+  adapter_path: ADAPTER_PATH,
+  args: [
+    {
+      name: "query",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Espacenet smart-search query (CQL-lite syntax)",
+    },
+    {
+      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) =>
+    runEspacenetSearch(kwargs as { query: string; limit?: number }),
+});

package/src/adapters/facebook/subtitles.ts

@@ -0,0 +1,44 @@
+/**
+ * @owner   Facebook subtitle adapter.
+ * @does    Extracts LLM-readable subtitle text from public Facebook video URLs.
+ * @needs   `yt-dlp` on PATH and an accessible video subtitle track.
+ * @feeds   Social video evidence gathering without browser-security bypasses.
+ * @breaks  Facebook or yt-dlp extractor changes can alter subtitle availability.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import { runVideoSubtitleExtraction } from "../../social/video-text.js";
+
+cli({
+  site: "facebook",
+  name: "subtitles",
+  description:
+    "Extract LLM-readable subtitles from a Facebook video URL with optional browser-cookie reuse",
+  domain: "www.facebook.com",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "url",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Facebook video URL",
+      format: "uri",
+    },
+    {
+      name: "languages",
+      type: "str",
+      default: "zh-Hans,zh,en",
+      description: "Comma-separated subtitle languages",
+    },
+    {
+      name: "cookies-from-browser",
+      type: "str",
+      description: "Browser name for yt-dlp --cookies-from-browser",
+    },
+  ],
+  columns: ["language", "text", "path"],
+  socialCapabilities: ["read", "media", "subtitles"],
+  defaultFormat: "json",
+  func: async (_page, kwargs) => runVideoSubtitleExtraction(kwargs),
+});