@zenalexa/unicli 0.220.0 → 0.221.0

package/src/adapters/vndb/web.ts

@@ -0,0 +1,393 @@
+/**
+ * @owner   src/adapters/vndb/web.ts
+ * @does    Register VNDB public visual novel, release, tag, staff, producer, and character lookup commands.
+ * @needs   VNDB Kana API JSON contract and public unauthenticated read endpoints.
+ * @feeds   ACG research workflows, visual novel discovery, game tag/type search.
+ * @breaks  VNDB field names or filter semantics drifting will hide games or metadata.
+ */
+
+import { USER_AGENT } from "../../constants.js";
+import { cli, Strategy } from "../../registry.js";
+
+const VNDB_API = "https://api.vndb.org/kana";
+
+interface VndbResponse {
+  more?: boolean;
+  results?: Record<string, unknown>[];
+}
+
+function str(value: unknown): string {
+  return value === undefined || value === null ? "" : String(value);
+}
+
+function requireQuery(value: unknown): string {
+  const query = str(value).trim();
+  if (!query) throw new Error("VNDB query cannot be empty.");
+  return query;
+}
+
+function requireLimit(value: unknown, fallback = 20): number {
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1 || n > 100) {
+    throw new Error("VNDB limit must be an integer in [1, 100].");
+  }
+  return n;
+}
+
+function normalizeId(value: unknown, prefix: string): string {
+  const raw = str(value).trim().toLowerCase();
+  if (!raw) throw new Error("VNDB id cannot be empty.");
+  return raw.startsWith(prefix) ? raw : `${prefix}${raw}`;
+}
+
+function joinNames(value: unknown, key = "name"): string {
+  return Array.isArray(value)
+    ? value
+        .map((item) => str((item as Record<string, unknown>)[key]))
+        .join(", ")
+    : "";
+}
+
+function joinStrings(value: unknown): string {
+  return Array.isArray(value) ? value.map(String).join(", ") : str(value);
+}
+
+function firstUrl(value: unknown): string {
+  if (!value || typeof value !== "object") return "";
+  return str((value as Record<string, unknown>).url);
+}
+
+function tagSummary(value: unknown): string {
+  if (!Array.isArray(value)) return "";
+  return value
+    .slice()
+    .sort(
+      (a, b) =>
+        Number((b as Record<string, unknown>).rating ?? 0) -
+        Number((a as Record<string, unknown>).rating ?? 0),
+    )
+    .slice(0, 12)
+    .map((item) => str((item as Record<string, unknown>).name))
+    .filter(Boolean)
+    .join(", ");
+}
+
+function sortValue(value: unknown, allowed: Record<string, string>): string {
+  const key = str(value || "relevance")
+    .toLowerCase()
+    .replace(/[\s_-]+/g, "");
+  const mapped = allowed[key];
+  if (!mapped) {
+    throw new Error(
+      `Unsupported VNDB sort: ${value}. Supported: ${Object.keys(allowed).join(", ")}.`,
+    );
+  }
+  return mapped;
+}
+
+async function vndbPost(
+  endpoint: string,
+  body: Record<string, unknown>,
+): Promise<Record<string, unknown>[]> {
+  const response = await fetch(`${VNDB_API}/${endpoint}`, {
+    method: "POST",
+    headers: {
+      Accept: "application/json",
+      "Content-Type": "application/json",
+      "User-Agent": USER_AGENT,
+    },
+    body: JSON.stringify(body),
+  });
+  if (!response.ok) {
+    throw new Error(
+      `VNDB ${endpoint} request failed with HTTP ${response.status}.`,
+    );
+  }
+  const json = (await response.json()) as VndbResponse;
+  return json.results ?? [];
+}
+
+function rankRows(rows: Record<string, unknown>[]): Record<string, unknown>[] {
+  return rows.map((row, index) => ({ rank: index + 1, ...row }));
+}
+
+export function mapVndbVisualNovels(
+  rows: Record<string, unknown>[],
+): Record<string, unknown>[] {
+  return rankRows(
+    rows.map((item) => ({
+      id: str(item.id),
+      title: str(item.title),
+      alttitle: str(item.alttitle),
+      released: str(item.released),
+      languages: joinStrings(item.languages),
+      platforms: joinStrings(item.platforms),
+      rating: item.rating ?? "",
+      votecount: item.votecount ?? "",
+      developers: joinNames(item.developers),
+      tags: tagSummary(item.tags),
+      image: firstUrl(item.image),
+      url: `https://vndb.org/${str(item.id)}`,
+    })),
+  );
+}
+
+export function mapVndbReleases(
+  rows: Record<string, unknown>[],
+): Record<string, unknown>[] {
+  return rankRows(
+    rows.map((item) => ({
+      id: str(item.id),
+      title: str(item.title),
+      released: str(item.released),
+      platforms: joinStrings(item.platforms),
+      producers: joinNames(item.producers),
+      vns: joinNames(item.vns, "title"),
+      url: `https://vndb.org/${str(item.id)}`,
+    })),
+  );
+}
+
+function mapSimple(
+  rows: Record<string, unknown>[],
+  urlPrefix: string,
+): Record<string, unknown>[] {
+  return rankRows(
+    rows.map((item) => ({
+      id: str(item.id),
+      name: str(item.name),
+      original: str(item.original),
+      category: str(item.category),
+      type: str(item.type),
+      lang: str(item.lang),
+      aliases: joinStrings(item.aliases),
+      description: str(item.description).replace(/\s+/g, " ").slice(0, 500),
+      url: `https://vndb.org/${urlPrefix}${str(item.id).replace(/^[a-z]+/, "")}`,
+    })),
+  );
+}
+
+async function searchVn(kwargs: Record<string, unknown>) {
+  const sort = sortValue(kwargs.sort, {
+    relevance: "searchrank",
+    rating: "rating",
+    votes: "votecount",
+    votecount: "votecount",
+    released: "released",
+    time: "released",
+    title: "title",
+  });
+  const rows = await vndbPost("vn", {
+    filters: ["search", "=", requireQuery(kwargs.query)],
+    fields:
+      "id,title,alttitle,released,languages,platforms,rating,votecount,image.url,tags.rating,tags.name,tags.category,developers.name",
+    sort,
+    reverse: kwargs.reverse === true,
+    results: requireLimit(kwargs.limit),
+  });
+  return mapVndbVisualNovels(rows);
+}
+
+const VN_COLUMNS = [
+  "rank",
+  "id",
+  "title",
+  "alttitle",
+  "released",
+  "languages",
+  "platforms",
+  "rating",
+  "votecount",
+  "developers",
+  "tags",
+  "url",
+];
+
+cli({
+  site: "vndb",
+  name: "search",
+  description: "Search VNDB visual novels by title, alias, tag, or keyword",
+  domain: "api.vndb.org",
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    { name: "query", type: "str", required: true, positional: true },
+    { name: "limit", type: "int", default: 20 },
+    {
+      name: "sort",
+      type: "str",
+      default: "relevance",
+      description: "relevance, rating, votes, released, time, title",
+    },
+    { name: "reverse", type: "bool", default: false },
+  ],
+  columns: VN_COLUMNS,
+  func: async (_page, kwargs) => searchVn(kwargs),
+});
+
+cli({
+  site: "vndb",
+  name: "vn",
+  description: "Get VNDB visual novel details by v-id",
+  domain: "api.vndb.org",
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [{ name: "id", type: "str", required: true, positional: true }],
+  columns: VN_COLUMNS,
+  func: async (_page, kwargs) =>
+    mapVndbVisualNovels(
+      await vndbPost("vn", {
+        filters: ["id", "=", normalizeId(kwargs.id, "v")],
+        fields:
+          "id,title,alttitle,released,languages,platforms,rating,votecount,image.url,tags.rating,tags.name,tags.category,developers.name",
+        results: 1,
+      }),
+    ),
+});
+
+cli({
+  site: "vndb",
+  name: "releases",
+  description: "Search VNDB releases by title or visual novel keyword",
+  domain: "api.vndb.org",
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    { name: "query", type: "str", required: true, positional: true },
+    { name: "limit", type: "int", default: 20 },
+    {
+      name: "sort",
+      type: "str",
+      default: "released",
+      description: "released, time, title",
+    },
+    { name: "reverse", type: "bool", default: true },
+  ],
+  columns: [
+    "rank",
+    "id",
+    "title",
+    "released",
+    "platforms",
+    "producers",
+    "vns",
+    "url",
+  ],
+  func: async (_page, kwargs) =>
+    mapVndbReleases(
+      await vndbPost("release", {
+        filters: ["search", "=", requireQuery(kwargs.query)],
+        fields: "id,title,released,platforms,producers.name,vns.title",
+        sort: sortValue(kwargs.sort, {
+          released: "released",
+          time: "released",
+          title: "title",
+        }),
+        reverse: kwargs.reverse !== false,
+        results: requireLimit(kwargs.limit),
+      }),
+    ),
+});
+
+cli({
+  site: "vndb",
+  name: "tags",
+  description: "Search VNDB game tags and genres",
+  domain: "api.vndb.org",
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    { name: "query", type: "str", required: true, positional: true },
+    { name: "limit", type: "int", default: 20 },
+  ],
+  columns: ["rank", "id", "name", "category", "description", "url"],
+  func: async (_page, kwargs) =>
+    mapSimple(
+      await vndbPost("tag", {
+        filters: ["search", "=", requireQuery(kwargs.query)],
+        fields: "id,name,category,description",
+        results: requireLimit(kwargs.limit),
+      }),
+      "g",
+    ),
+});
+
+cli({
+  site: "vndb",
+  name: "staff",
+  description: "Search VNDB creators and staff",
+  domain: "api.vndb.org",
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    { name: "query", type: "str", required: true, positional: true },
+    { name: "limit", type: "int", default: 20 },
+  ],
+  columns: ["rank", "id", "name", "original", "lang", "description", "url"],
+  func: async (_page, kwargs) =>
+    mapSimple(
+      await vndbPost("staff", {
+        filters: ["search", "=", requireQuery(kwargs.query)],
+        fields: "id,name,original,lang,gender,description",
+        results: requireLimit(kwargs.limit),
+      }),
+      "s",
+    ),
+});
+
+cli({
+  site: "vndb",
+  name: "producers",
+  description:
+    "Search VNDB producers, studios, brands, makers, circles, companies, and visual novel publishers such as Yuzusoft",
+  domain: "api.vndb.org",
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    { name: "query", type: "str", required: true, positional: true },
+    { name: "limit", type: "int", default: 20 },
+  ],
+  columns: [
+    "rank",
+    "id",
+    "name",
+    "aliases",
+    "lang",
+    "type",
+    "description",
+    "url",
+  ],
+  func: async (_page, kwargs) =>
+    mapSimple(
+      await vndbPost("producer", {
+        filters: ["search", "=", requireQuery(kwargs.query)],
+        fields: "id,name,aliases,lang,type,description",
+        results: requireLimit(kwargs.limit),
+      }),
+      "p",
+    ),
+});
+
+cli({
+  site: "vndb",
+  name: "characters",
+  description: "Search VNDB characters and traits",
+  domain: "api.vndb.org",
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    { name: "query", type: "str", required: true, positional: true },
+    { name: "limit", type: "int", default: 20 },
+  ],
+  columns: ["rank", "id", "name", "original", "description", "url"],
+  func: async (_page, kwargs) =>
+    mapSimple(
+      await vndbPost("character", {
+        filters: ["search", "=", requireQuery(kwargs.query)],
+        fields: "id,name,original,sex,description,vns.title,traits.name",
+        results: requireLimit(kwargs.limit),
+      }),
+      "c",
+    ),
+});

package/src/adapters/wipo-patentscope/info.yaml

@@ -0,0 +1,43 @@
+# @owner       src::adapters::wipo-patentscope::info
+# @does        Registry placeholder for WIPO PATENTSCOPE — surfaces a structured PATENT_API_DEPRECATED envelope so `unicli patent doctor` and `unicli list` advertise the gap, without claiming false coverage.
+# @needs       src/engine/steps/assert.ts
+# @feeds       src/commands/patent.ts (meta-command discovery via `patent.*` capability)
+# @breaks      always throws PipelineError carrying a PATENT_API_DEPRECATED message; never silently returns rows
+# @invariants  no HTTPS egress; no env reads; no caller-visible state beyond the error envelope
+# @side-effects none — the assertion is purely local
+# @perf        n/a — fails before any I/O
+# @concurrency safe (pure local assertion)
+# @test        none yet
+# @stability   experimental — replace with a real adapter when WIPO ships a token-based REST/GraphQL API
+# @since       2026-05-18
+# @verification blocked-by-subscription — PATENTSCOPE exposes only a SOAP web service that requires a paid subscription (~CHF 600/year per third-party gem README; see https://patentscope.wipo.int/search/en/sub_user.jsf). Until WIPO ships a token-based REST/GraphQL surface, this adapter is a registry placeholder.
+site: wipo-patentscope
+name: info
+description: WIPO PATENTSCOPE registry placeholder — no public REST API; SOAP requires subscription
+domain: patentscope.wipo.int
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args: {}
+
+pipeline:
+  # Fail closed with a structured envelope that the agent can read and act on.
+  # The message names the upstream channel and the subscription URL so the
+  # caller has a concrete next step — no silent fallback, no fake row.
+  - assert:
+      condition: "false"
+      message: "PATENT_API_DEPRECATED: WIPO PATENTSCOPE exposes only a SOAP web service that requires a paid subscription. Subscribe at https://patentscope.wipo.int/search/en/sub_user.jsf, or fall back to Espacenet for WO-prefixed publications (EPO brokers PCT family lookups)."
+
+columns: []
+
+# schema-v2 metadata
+# The patent.* capability is what makes `unicli patent doctor` discover this
+# adapter so the gap is reported in the doctor table; assert.fail is the
+# step the dispatcher actually invokes at runtime.
+capabilities: ["assert", "patent.search", "patent.get"]
+minimum_capability: assert
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/xiaohongshu/browser-state.ts

@@ -0,0 +1,95 @@
+/**
+ * @owner   Xiaohongshu browser adapters.
+ * @does    Detects login, risk-control, and rendered-feed state in XHS web pages.
+ * @needs   Browser-backed IPage from Uni-CLI runtime.
+ * @feeds   xiaohongshu.search and xiaohongshu.trending.
+ * @breaks  XHS copy or route changes can require updating page-state detection.
+ */
+
+import type { IPage } from "../../types.js";
+import {
+  socialAuthError,
+  socialChallengeError,
+} from "../../social/browser-errors.js";
+
+interface XhsPageState {
+  url: string;
+  title: string;
+  text: string;
+}
+
+export async function readXhsPageState(page: IPage): Promise<XhsPageState> {
+  const raw = await page.evaluate(`
+    (() => ({
+      url: window.location.href,
+      title: document.title || '',
+      text: (document.body?.innerText || '').replace(/\\s+/g, ' ').slice(0, 2000)
+    }))()
+  `);
+  const state = raw as Partial<XhsPageState>;
+  return {
+    url: String(state.url ?? ""),
+    title: String(state.title ?? ""),
+    text: String(state.text ?? ""),
+  };
+}
+
+export function assertXhsReadableState(
+  command: string,
+  state: XhsPageState,
+): void {
+  const haystack = `${state.url}\n${state.title}\n${state.text}`;
+  if (
+    /website-login\/error|安全限制|IP存在风险|风险|风控|安全验证|验证码|人机验证|verify|captcha/i.test(
+      haystack,
+    )
+  ) {
+    throw socialChallengeError(
+      "xiaohongshu",
+      command,
+      `Xiaohongshu is showing a risk-control or verification page: ${state.title || state.url}`,
+    );
+  }
+  if (/登录后查看|登录后|请先登录|login/i.test(haystack)) {
+    throw socialAuthError("xiaohongshu", command);
+  }
+}
+
+export async function assertXhsReadable(
+  page: IPage,
+  command: string,
+): Promise<void> {
+  assertXhsReadableState(command, await readXhsPageState(page));
+}
+
+export async function fetchXhsFeedItems(page: IPage): Promise<unknown[]> {
+  const raw = await page.evaluate(`
+    (async () => {
+      const app = document.querySelector('#app')?.__vue_app__;
+      if (!app) throw new Error('Xiaohongshu Vue app not found');
+      const pinia = app.config?.globalProperties?.$pinia;
+      if (!pinia || !pinia._s?.has('feed')) throw new Error('Xiaohongshu feed store not found');
+      const store = pinia._s.get('feed');
+      const captured = [];
+      const originalFetch = window.fetch;
+      window.fetch = async (...args) => {
+        const response = await originalFetch(...args);
+        try {
+          const url = String(args[0]?.url || args[0] || '');
+          if (/homefeed|feed/i.test(url)) {
+            captured.push(await response.clone().json());
+          }
+        } catch {}
+        return response;
+      };
+      try {
+        await store.fetchFeeds();
+      } finally {
+        window.fetch = originalFetch;
+      }
+      const payload = captured.find((item) => item?.data?.items?.length) || captured[0];
+      return payload?.data?.items || [];
+    })()
+  `);
+  return Array.isArray(raw) ? raw : [];
+}

package/src/adapters/xiaohongshu/comments.ts

@@ -7,6 +7,7 @@
 
 import { cli, Strategy } from "../../registry.js";
 import type { IPage } from "../../types.js";
+import { normalizeCommentRows } from "../../social/comments.js";
 import { buildNoteUrl } from "./note-helpers.js";
 
 function parseCommentLimit(raw: unknown, fallback = 20): number {
@@ -42,7 +43,23 @@ cli({
       description: "Include nested replies",
     },
   ],
-  columns: ["rank", "author", "text", "likes", "time", "is_reply", "reply_to"],
+  columns: [
+    "rank",
+    "platform",
+    "content_id",
+    "comment_id",
+    "parent_id",
+    "depth",
+    "path",
+    "author",
+    "text",
+    "likes",
+    "replies",
+    "created",
+    "time",
+    "is_reply",
+    "reply_to",
+  ],
   func: async (page, kwargs) => {
     const p = page as IPage;
     const limit = parseCommentLimit(kwargs.limit);
@@ -100,7 +117,7 @@ cli({
           const likes = parseLikes(item.querySelector('.count'))
           const time = clean(item.querySelector('.date, .time'))
           if (!text) continue
-          results.push({ author, text, likes, time, is_reply: false, reply_to: '' })
+          results.push({ author, text, likes, replies: 0, created: time, time, is_reply: false, reply_to: '' })
           if (withReplies) {
             await expandReplyThreads(p)
             p.querySelectorAll('.reply-container .comment-item-sub, .sub-comment-list .comment-item').forEach(sub => {
@@ -109,7 +126,7 @@ cli({
               const sLikes = parseLikes(sub.querySelector('.count'))
               const sTime = clean(sub.querySelector('.date, .time'))
               if (!sText) return
-              results.push({ author: sAuthor, text: sText, likes: sLikes, time: sTime, is_reply: true, reply_to: author })
+              results.push({ author: sAuthor, text: sText, likes: sLikes, replies: 0, created: sTime, time: sTime, is_reply: true, reply_to: author })
             })
           }
         }
@@ -125,7 +142,7 @@ cli({
       throw new Error("Note comments require login to www.xiaohongshu.com");
     }
 
-    interface CommentRow {
+    interface CommentRow extends Record<string, unknown> {
       author: string;
       text: string;
       likes: number;
@@ -144,9 +161,15 @@ cli({
         if (topCount > limit) break;
         limited.push(c);
       }
-      return limited.map((c, i) => ({ rank: i + 1, ...c }));
+      return normalizeCommentRows(limited, {
+        platform: "xiaohongshu",
+        contentId: raw,
+      }).map((c, i) => ({ rank: i + 1, ...c }));
     }
 
-    return all.slice(0, limit).map((c, i) => ({ rank: i + 1, ...c }));
+    return normalizeCommentRows(all.slice(0, limit), {
+      platform: "xiaohongshu",
+      contentId: raw,
+    }).map((c, i) => ({ rank: i + 1, ...c }));
   },
 });