@zenalexa/unicli 0.220.0 → 0.221.0

package/src/adapters/jpo/search.yaml

@@ -0,0 +1,76 @@
+# @owner       src::adapters::jpo::search
+# @does        Search JPO Patent Information Retrieval API for Japanese patent applications.
+# @needs       src/engine/steps/fetch.ts, src/engine/steps/select.ts, src/engine/steps/map.ts, src/engine/steps/limit.ts
+# @feeds       src/commands/patent.ts
+# @breaks      throws PipelineError on 401/403 (missing JPO_API_TOKEN), 404, 5xx; rate-limited per terms-of-use
+# @invariants  output rows conform to PatentRecord; publication_number is `JP-<doc>-<kind>`
+# @side-effects reads env JPO_API_TOKEN; HTTPS egress to ip-data.jpo.go.jp
+# @perf        single request
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key — needs JPO_API_TOKEN (registration at jpo.go.jp/e/system/laws/koho/internet/api-patent_info.html); exact path verified at live exercise time
+site: jpo
+name: search
+description: Search JPO Patent Information Retrieval API
+domain: ip-data.jpo.go.jp
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+    description: Free-text query (JPO maps to title/abstract/applicant fields)
+  limit:
+    type: int
+    default: 25
+    description: Maximum results
+
+pipeline:
+  - fetch:
+      url: "https://ip-data.jpo.go.jp/api/v2/patent/applications/search"
+      method: GET
+      headers:
+        Accept: application/json
+        Authorization: "Bearer ${{ env.JPO_API_TOKEN || '' }}"
+      params:
+        q: "${{ args.query }}"
+        size: "${{ args.limit }}"
+
+  - select: results
+
+  # JPO Patent Information Retrieval JSON; preserve Japanese script in title,
+  # surface English title when JPO returns one, expose IPC + applicant fields.
+  - map:
+      publication_number: "${{ 'JP-' + (item.publicationNumber || item.applicationNumber || '') + '-' + (item.publicationKindCode || '') }}"
+      application_number: "${{ item.applicationNumber || '' }}"
+      title: "${{ item.inventionTitleJapanese || item.inventionTitleEnglish || '' }}"
+      abstract: "${{ item.abstractJapanese || item.abstractEnglish || '' }}"
+      kind_code: "${{ item.publicationKindCode || '' }}"
+      filing_date: "${{ item.applicationDate || '' }}"
+      publication_date: "${{ item.publicationDate || '' }}"
+      grant_date: "${{ item.registrationDate || '' }}"
+      priority_date: "${{ item.priorityDate || '' }}"
+      # JPO returns inventor / applicant as either string or string[]; coerce to array.
+      inventors: "${{ JSON.stringify((function(){ var i=item.inventorName; if(!i) return []; var arr = Array.isArray(i) ? i : [i]; return arr.map(n => ({ name: typeof n === 'string' ? n : (n.name || ''), country: 'JP' })).filter(x => x.name); })()) }}"
+      assignees: "${{ JSON.stringify((function(){ var a=item.applicantName; if(!a) return []; var arr = Array.isArray(a) ? a : [a]; return arr.map(n => ({ name: typeof n === 'string' ? n : (n.name || ''), country: 'JP' })).filter(x => x.name); })()) }}"
+      classifications: "${{ JSON.stringify((function(){ var c=item.ipcClassification; if(!c) return []; var arr = Array.isArray(c) ? c : [c]; return arr.map(x => ({ scheme: 'ipc', code: typeof x === 'string' ? x : (x.code || '') })).filter(x => x.code); })()) }}"
+      source_adapter: jpo
+      source_url: "${{ 'https://www.j-platpat.inpit.go.jp/p0200' }}"
+      retrieved_at: ""
+
+  - limit: "${{ args.limit }}"
+
+columns: [publication_number, title, filing_date, publication_date]
+
+# schema-v2 metadata
+capabilities: ["http.fetch", "patent.search"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/kipris/get.yaml

@@ -0,0 +1,69 @@
+# @owner       src::adapters::kipris::get
+# @does        Fetch a single Korean patent bibliographic record from KIPRIS Plus REST by application number.
+# @needs       src/engine/steps/fetch.ts, src/engine/steps/select-xml.ts, src/engine/steps/map.ts
+# @feeds       src/commands/patent.ts
+# @breaks      throws PipelineError on missing key, 4xx, 5xx
+# @invariants  output row conforms to PatentRecord
+# @side-effects reads env KIPRIS_ACCESS_KEY; HTTPS egress to plus.kipris.or.kr
+# @perf        single request
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key
+site: kipris
+name: get
+description: Fetch a KIPRIS biblio record by application number
+domain: plus.kipris.or.kr
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  application_number:
+    type: str
+    required: true
+    positional: true
+    description: Korean application number (e.g. 1020230012345)
+
+pipeline:
+  - fetch:
+      url: "https://plus.kipris.or.kr/openapi/rest/patUtiModInfoSearchSevice/getBibliographyDetailInfoSearch"
+      method: GET
+      headers:
+        Accept: application/xml
+      params:
+        applicationNumber: "${{ args.application_number }}"
+        accessKey: "${{ env.KIPRIS_ACCESS_KEY || '' }}"
+
+  - select-xml:
+      xpath: "//biblioSummaryInfo"
+      unwrap_single: true
+
+  - map:
+      publication_number: "${{ 'KR-' + (item.openNumber || args.application_number || '') + '-' + (item.openType || '') }}"
+      application_number: "${{ item.applicationNumber || args.application_number || '' }}"
+      title: "${{ item.inventionTitle || '' }}"
+      abstract: "${{ item.astrtCont || '' }}"
+      kind_code: "${{ item.openType || '' }}"
+      filing_date: "${{ item.applicationDate || '' }}"
+      publication_date: "${{ item.openDate || '' }}"
+      grant_date: "${{ item.registerDate || '' }}"
+      priority_date: "${{ item.priorityDate || '' }}"
+      legal_status: "${{ item.registerStatus || '' }}"
+      inventors: "${{ JSON.stringify(item.inventor ? [{ name: item.inventor, country: 'KR' }] : []) }}"
+      assignees: "${{ JSON.stringify(item.applicant ? [{ name: item.applicant, country: 'KR' }] : []) }}"
+      classifications: "${{ JSON.stringify((function(){ var c=item.ipcNumber; if(!c) return []; var arr = String(c).split('|').map(s => s.trim()).filter(s => s); return arr.map(code => ({ scheme: 'ipc', code: code })); })()) }}"
+      source_adapter: kipris
+      source_url: "${{ 'https://kpat.kipris.or.kr/kpat/biblioa.do?method=biblioFrame&applno=' + (args.application_number || '') }}"
+      retrieved_at: ""
+
+columns: [publication_number, title, filing_date, publication_date]
+
+# schema-v2 metadata
+capabilities: ["http.fetch", "patent.get"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/kipris/legal-status.yaml

@@ -0,0 +1,58 @@
+# @owner       src::adapters::kipris::legal-status
+# @does        Fetch Korean patent legal-status (right-trans/registration events) from KIPRIS Plus REST.
+# @needs       src/engine/steps/fetch.ts, src/engine/steps/select-xml.ts, src/engine/steps/map.ts
+# @feeds       src/commands/patent.ts
+# @breaks      throws PipelineError on missing key, 4xx, 5xx
+# @invariants  output rows carry legal_status from rightTransRegInfo
+# @side-effects reads env KIPRIS_ACCESS_KEY; HTTPS egress
+# @perf        single request
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key
+site: kipris
+name: legal-status
+description: KIPRIS right-trans / registration events for a Korean application
+domain: plus.kipris.or.kr
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  application_number:
+    type: str
+    required: true
+    positional: true
+    description: Korean application number
+
+pipeline:
+  - fetch:
+      url: "https://plus.kipris.or.kr/openapi/rest/patUtiModInfoSearchSevice/getRightTransRegInfoSearchInfo"
+      method: GET
+      headers:
+        Accept: application/xml
+      params:
+        applicationNumber: "${{ args.application_number }}"
+        accessKey: "${{ env.KIPRIS_ACCESS_KEY || '' }}"
+
+  - select-xml:
+      xpath: "//item"
+
+  - map:
+      publication_number: "${{ 'KR-' + (args.application_number || '') }}"
+      application_number: "${{ args.application_number }}"
+      legal_status: "${{ (item.rightCode || '') + ' ' + (item.contents || '') }}"
+      source_adapter: kipris
+      source_url: "${{ 'https://kpat.kipris.or.kr/kpat/biblioa.do?method=biblioFrame&applno=' + (args.application_number || '') }}"
+      retrieved_at: ""
+
+columns: [publication_number, legal_status]
+
+# schema-v2 metadata
+capabilities: ["http.fetch", "patent.legal-status"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/kipris/search.yaml

@@ -0,0 +1,79 @@
+# @owner       src::adapters::kipris::search
+# @does        Search KIPRIS Plus REST patent search endpoint for Korean patents/utility models.
+# @needs       src/engine/steps/fetch.ts, src/engine/steps/select-xml.ts, src/engine/steps/map.ts, src/engine/steps/limit.ts
+# @feeds       src/commands/patent.ts
+# @breaks      throws PipelineError on missing/invalid accessKey, 4xx, 5xx
+# @invariants  output rows conform to PatentRecord; publication_number is `KR-<doc>-<kind>`
+# @side-effects reads env KIPRIS_ACCESS_KEY; HTTPS egress to plus.kipris.or.kr
+# @perf        single request
+# @concurrency safe
+# @test        none yet
+# @stability   stable
+# @since       2026-05-18
+# @verification blocked-by-key — needs KIPRIS_ACCESS_KEY (registration at plus.kipris.or.kr)
+site: kipris
+name: search
+description: Search KIPRIS Plus REST for Korean patents/utility models
+domain: plus.kipris.or.kr
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+    description: Free-text query (KIPRIS `word` param)
+  limit:
+    type: int
+    default: 25
+    description: Maximum results (numOfRows)
+
+pipeline:
+  - fetch:
+      url: "https://plus.kipris.or.kr/openapi/rest/patUtiModInfoSearchSevice/getWordSearch"
+      method: GET
+      headers:
+        Accept: application/xml
+      params:
+        word: "${{ args.query }}"
+        numOfRows: "${{ args.limit }}"
+        pageNo: "1"
+        accessKey: "${{ env.KIPRIS_ACCESS_KEY || '' }}"
+
+  - select-xml:
+      xpath: "//item"
+
+  # KIPRIS Plus XML preserves the native Korean script for title / abstract.
+  - map:
+      publication_number: "${{ 'KR-' + (item.openNumber || item.applicationNumber || '') + '-' + (item.openType || '') }}"
+      application_number: "${{ item.applicationNumber || '' }}"
+      title: "${{ item.inventionTitle || '' }}"
+      abstract: "${{ item.astrtCont || '' }}"
+      kind_code: "${{ item.openType || '' }}"
+      filing_date: "${{ item.applicationDate || '' }}"
+      publication_date: "${{ item.openDate || '' }}"
+      grant_date: "${{ item.registerDate || '' }}"
+      priority_date: "${{ item.priorityNumber ? (item.priorityDate || '') : '' }}"
+      legal_status: "${{ item.registerStatus || '' }}"
+      # KIPRIS exposes inventor / applicant as a single concatenated string;
+      # preserve the format the office returns and treat it as one party.
+      inventors: "${{ JSON.stringify(item.inventor ? [{ name: item.inventor, country: 'KR' }] : []) }}"
+      assignees: "${{ JSON.stringify(item.applicant ? [{ name: item.applicant, country: 'KR' }] : []) }}"
+      classifications: "${{ JSON.stringify((function(){ var c=item.ipcNumber; if(!c) return []; var arr = String(c).split('|').map(s => s.trim()).filter(s => s); return arr.map(code => ({ scheme: 'ipc', code: code })); })()) }}"
+      source_adapter: kipris
+      source_url: "${{ 'https://kpat.kipris.or.kr/kpat/biblioa.do?method=biblioFrame&applno=' + (item.applicationNumber || '') }}"
+      retrieved_at: ""
+
+  - limit: "${{ args.limit }}"
+
+columns: [publication_number, title, filing_date, publication_date]
+
+# schema-v2 metadata
+capabilities: ["http.fetch", "patent.search"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/kitsu/web.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { resolveCommand } from "../../registry.js";
+import { mapKitsuMedia } from "./web.js";
+
+describe("kitsu public commands", () => {
+  it("registers anime and manga commands", () => {
+    expect(
+      Object.keys(resolveCommand("kitsu", "anime")!.adapter.commands),
+    ).toEqual(expect.arrayContaining(["anime", "manga"]));
+  });
+
+  it("maps media rows", () => {
+    expect(
+      mapKitsuMedia([
+        {
+          id: "12794",
+          type: "anime",
+          attributes: {
+            canonicalTitle: "Fireworks",
+            slug: "uchiage-hanabi",
+            subtype: "movie",
+          },
+        },
+      ]),
+    ).toMatchObject([
+      { rank: 1, id: "12794", title: "Fireworks", subtype: "movie" },
+    ]);
+  });
+});

package/src/adapters/kitsu/web.ts

@@ -0,0 +1,109 @@
+/**
+ * @owner   src/adapters/kitsu/web.ts
+ * @does    Register Kitsu public anime and manga search commands.
+ * @needs   Kitsu JSON:API text filters and public media pages.
+ * @feeds   ACG title discovery with community rating and subtype metadata.
+ * @breaks  Kitsu JSON:API field changes or service availability can block lookup.
+ */
+
+import { USER_AGENT } from "../../constants.js";
+import { cli, Strategy } from "../../registry.js";
+
+const API = "https://kitsu.io/api/edge";
+
+function str(value: unknown): string {
+  return value === undefined || value === null ? "" : String(value);
+}
+
+function required(value: unknown): string {
+  const text = str(value).trim();
+  if (!text) throw new Error("kitsu query cannot be empty.");
+  return text;
+}
+
+function requireLimit(value: unknown): number {
+  if (value === undefined || value === null || value === "") return 10;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1 || n > 20) {
+    throw new Error("kitsu limit must be an integer in [1, 20].");
+  }
+  return n;
+}
+
+export function mapKitsuMedia(rows: unknown[]): Record<string, unknown>[] {
+  return rows.map((row, index) => {
+    const item = row as Record<string, unknown>;
+    const attrs =
+      (item.attributes as Record<string, unknown> | undefined) ?? {};
+    const titles = (attrs.titles as Record<string, unknown> | undefined) ?? {};
+    return {
+      rank: index + 1,
+      id: item.id,
+      type: item.type,
+      title: str(
+        attrs.canonicalTitle || titles.en || titles.en_jp || titles.ja_jp,
+      ),
+      subtype: str(attrs.subtype),
+      status: str(attrs.status),
+      start_date: str(attrs.startDate),
+      average_rating: str(attrs.averageRating),
+      popularity_rank: attrs.popularityRank ?? null,
+      synopsis: str(attrs.synopsis).slice(0, 500),
+      url: `https://kitsu.io/${item.type}/${attrs.slug || item.id}`,
+    };
+  });
+}
+
+async function search(
+  kind: "anime" | "manga",
+  kwargs: Record<string, unknown>,
+) {
+  const query = required(kwargs.query);
+  const cap = requireLimit(kwargs.limit);
+  const url = new URL(`${API}/${kind}`);
+  url.searchParams.set("filter[text]", query);
+  url.searchParams.set("page[limit]", String(cap));
+  const response = await fetch(url, {
+    headers: {
+      Accept: "application/vnd.api+json",
+      "User-Agent": USER_AGENT,
+    },
+  });
+  if (!response.ok)
+    throw new Error(`kitsu request failed with HTTP ${response.status}.`);
+  const data = (await response.json()) as { data?: unknown[] };
+  const rows = mapKitsuMedia(data.data ?? []);
+  if (rows.length === 0)
+    throw new Error(`No Kitsu ${kind} found for "${query}".`);
+  return rows;
+}
+
+const ARGS = [
+  { name: "query", type: "str" as const, required: true, positional: true },
+  { name: "limit", type: "int" as const, default: 10 },
+];
+const COLUMNS = [
+  "rank",
+  "id",
+  "type",
+  "title",
+  "subtype",
+  "status",
+  "start_date",
+  "average_rating",
+  "url",
+];
+
+for (const name of ["anime", "manga"] as const) {
+  cli({
+    site: "kitsu",
+    name,
+    description: `Search Kitsu ${name} by Japanese title, romaji, alias, or keyword`,
+    domain: "kitsu.io",
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: ARGS,
+    columns: COLUMNS,
+    func: async (_page, kwargs) => search(name, kwargs),
+  });
+}

package/src/adapters/konachan/detail.yaml

@@ -0,0 +1,62 @@
+site: konachan
+name: detail
+description: Get Konachan post detail by post id
+domain: konachan.com
+type: web-api
+strategy: public
+
+args:
+  id:
+    type: str
+    required: true
+    positional: true
+
+pipeline:
+  - fetch:
+      url: "https://konachan.com/post.json"
+      params:
+        tags: "${{ 'id:' + args.id }}"
+        limit: 1
+
+  - assert:
+      condition: "data.length > 0"
+      message: "No Konachan post found for this id."
+
+  - map:
+      id: "${{ item.id }}"
+      rating: "${{ item.rating }}"
+      score: "${{ item.score }}"
+      author: "${{ item.author }}"
+      created_at: "${{ item.created_at }}"
+      width: "${{ item.width }}"
+      height: "${{ item.height }}"
+      file_ext: "${{ item.file_ext }}"
+      file_size: "${{ item.file_size }}"
+      tags: "${{ item.tags }}"
+      source: "${{ item.source }}"
+      preview_url: "${{ item.preview_url }}"
+      sample_url: "${{ item.sample_url }}"
+      file_url: "${{ item.file_url }}"
+      url: "${{ 'https://konachan.com/post/show/' + item.id }}"
+
+columns:
+  [
+    id,
+    rating,
+    score,
+    author,
+    width,
+    height,
+    tags,
+    source,
+    sample_url,
+    file_url,
+    url,
+  ]
+
+capabilities: ["http.fetch"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/konachan/download.yaml

@@ -0,0 +1,55 @@
+site: konachan
+name: download
+description: Download Konachan post image by post id
+domain: konachan.com
+type: web-api
+strategy: public
+
+args:
+  id:
+    type: str
+    required: true
+    positional: true
+  output:
+    type: str
+    default: "./downloads/konachan"
+    description: Output directory
+    x-unicli-kind: path
+  quality:
+    type: str
+    default: sample
+    description: sample or original
+
+columns: [id, rating, tags, url, _download]
+
+pipeline:
+  - fetch:
+      url: "https://konachan.com/post.json"
+      params:
+        tags: "${{ 'id:' + args.id }}"
+        limit: 1
+
+  - assert:
+      condition: "data.length > 0"
+      message: "No Konachan post found for this id."
+
+  - download:
+      url: "${{ args.quality === 'original' ? item.file_url : item.sample_url }}"
+      dir: "${{ args.output }}"
+      filename: "${{ item.id }}.${{ (args.quality === 'original' ? item.file_url : item.sample_url) | ext | default('jpg') }}"
+      type: image
+      concurrency: 1
+
+  - map:
+      id: "${{ item.id }}"
+      rating: "${{ item.rating }}"
+      tags: "${{ item.tags }}"
+      url: "${{ 'https://konachan.com/post/show/' + item.id }}"
+      _download: "${{ item._download }}"
+
+capabilities: ["http.fetch", "http.download"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/konachan/search.yaml

@@ -0,0 +1,65 @@
+site: konachan
+name: search
+description: Search Konachan illustration posts by Japanese, romaji, or Moebooru tag query
+domain: konachan.com
+type: web-api
+strategy: public
+
+args:
+  tags:
+    type: str
+    required: true
+    positional: true
+    description: Tag query, for example "rating:safe" or "sparkle_(honkai:_star_rail)"
+  limit:
+    type: int
+    default: 20
+  page:
+    type: int
+    default: 1
+
+pipeline:
+  - fetch:
+      url: "https://konachan.com/post.json"
+      params:
+        tags: "${{ args.tags }}"
+        limit: "${{ args.limit }}"
+        page: "${{ args.page }}"
+
+  - map:
+      rank: "${{ index + 1 }}"
+      id: "${{ item.id }}"
+      rating: "${{ item.rating }}"
+      score: "${{ item.score }}"
+      author: "${{ item.author }}"
+      width: "${{ item.width }}"
+      height: "${{ item.height }}"
+      tags: "${{ item.tags }}"
+      source: "${{ item.source }}"
+      preview_url: "${{ item.preview_url }}"
+      sample_url: "${{ item.sample_url }}"
+      file_url: "${{ item.file_url }}"
+      url: "${{ 'https://konachan.com/post/show/' + item.id }}"
+
+columns:
+  [
+    rank,
+    id,
+    rating,
+    score,
+    author,
+    width,
+    height,
+    tags,
+    source,
+    sample_url,
+    file_url,
+    url,
+  ]
+
+capabilities: ["http.fetch"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/konachan/tags.yaml

@@ -0,0 +1,40 @@
+site: konachan
+name: tags
+description: Search Konachan tags by Japanese name, romaji, or tag prefix
+domain: konachan.com
+type: web-api
+strategy: public
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+  limit:
+    type: int
+    default: 20
+
+pipeline:
+  - fetch:
+      url: "https://konachan.com/tag.json"
+      params:
+        name: "${{ args.query }}"
+        limit: "${{ args.limit }}"
+
+  - map:
+      rank: "${{ index + 1 }}"
+      id: "${{ item.id }}"
+      name: "${{ item.name }}"
+      count: "${{ item.count }}"
+      type: "${{ item.type }}"
+      ambiguous: "${{ item.ambiguous }}"
+      url: "${{ 'https://konachan.com/post?tags=' + encodeURIComponent(item.name) }}"
+
+columns: [rank, id, name, count, type, ambiguous, url]
+
+capabilities: ["http.fetch"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2