dsh-paper-search 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+## Compatibility
+
+| dsh-paper-search | DeepSeek Harness | Diuji pada |
+|---|---|---|
+| 0.1.0 | 0.1.7-rc.2 | 28 Sep 2026, Windows, Node 24 |
+
+Paket ini tidak memakai API internal DSH selain `ctx.tools.register` dan
+`ctx.get('skills').registerProvider` — keduanya sudah dipakai plugin lain yang
+berjalan di profil ini (`dsh-search-cascade`), jadi titik patahnya sama dan sudah
+diketahui.
+
+## [0.1.0] - 2026-09-28
+
+Rilis pertama.
+
+### Added
+
+- **Enam belas sumber lewat satu tool `paper_search`**, semuanya native HTTP:
+  - **tiga belas internasional** — Crossref, OpenAlex, DOAJ, Europe PMC, PubMed,
+    PubMed Central, arXiv, Semantic Scholar, CORE, Zenodo, HAL lewat REST API
+    JSON; IACR ePrint lewat penguraian HTML; Unpaywall lewat REST API dengan
+    **input DOI** (bukan kata kunci);
+  - **tiga portal Indonesia** lewat penguraian halaman publik — Garuda (artikel
+    jurnal), Sinta (daftar jurnal terakreditasi), IOS OneSearch (agregator
+    repositori).
+- **Sumber ber-input DOI ditandai di registry** (`input: 'doi'`). Saat pengguna
+  mencari dengan kata kunci, `unpaywall` **dilewati** — bukan dijalankan lalu
+  dilaporkan kosong — dan alasan pelewatan itu dicetak dalam keluaran. Saat
+  diminta eksplisit, ia tetap dijalankan dan mengembalikan kosong, karena
+  memang begitulah perilakunya.
+- **Dua sumber wajib kredensial**, masing-masing dilaporkan sebagai kegagalan
+  yang bisa ditindaklanjuti, bukan 429 yang membingungkan:
+  `core` butuh `CORE_API_KEY`; `unpaywall` butuh email.
+- **Dedup** berdasarkan DOI lalu judul yang dinormalkan; setiap hasil mencatat
+  **semua** sumber yang menemukannya, bukan menyembunyikan yang lain.
+- **Tool `paper_status`** — mengirim satu permintaan kecil ke tiap sumber dan
+  melaporkan mana yang benar-benar menjawab, plus kredensial mana yang terbaca
+  **beserta dari mana asalnya** (config plugin / variabel lingkungan /
+  `.env` milik CLI upstream).
+- **Registrasi skill `paper-search`** lewat `ctx.get('skills').registerProvider()`
+  di rank **450** — sengaja kalah dari berkas di `~/.dsh/skills` (rank 400)
+  supaya suntingan pengguna selalu menang. Dibaca ulang setiap kali, tidak
+  di-cache, jadi suntingan `SKILL.md` langsung terpakai tanpa restart.
+- **Pembatas laju arXiv sendiri** (1 permintaan / 3 detik) sesuai TOU mereka,
+  walau sumber lain dipanggil paralel.
+
+### Fixed
+
+- Judul Garuda yang diulang oleh markup `<xmp>`-nya (terukur: judul 44 huruf
+  diulang ~6× menjadi 255 huruf) kini diringkas menjadi satu salinan. Aturannya
+  konservatif — hanya bila pengulangannya persis dari awal sampai akhir.
+- DOI dinormalkan tanpa awalan URL (`https://doi.org/...`) supaya dedup bekerja
+  lintas sumber.
+
+### Catatan kejujuran
+
+- **Sembilan sumber publik SENGAJA TIDAK didaftarkan**, masing-masing dengan
+  alasan yang diukur 28 Sep 2026 — bukan karena lupa:
+
+  | Sumber | Alasan |
+  |---|---|
+  | `moraref` | hanya halaman pendarat, tanpa markup hasil (3.964 huruf) |
+  | `dblp` | API di balik proteksi bot — mengembalikan halaman "Making sure you're not a bot!", bukan JSON |
+  | `openaire` | permintaan uji **timeout 30 detik dan 40 detik** |
+  | `biorxiv` | API-nya berbasis **rentang tanggal**, bukan pencarian kata kunci |
+  | `medrxiv` | sama seperti `biorxiv` |
+  | `base` | OAuth/OAI-PMH menolak: `Access denied for IP address 182.8.249.89…` — butuh pendaftaran IP institusi |
+  | `citeseerx` | HTTP 404, lalu **menggantung** sampai permintaannya dibunuh |
+  | `ssrn` | menolak permintaan biasa dengan HTTP 403 |
+  | `google_scholar` | deteksi bot aktif, butuh proxy |
+
+  Sumber yang selalu kosong lebih buruk daripada sumber yang tidak ada, jadi
+  yang gagal dibuang **beserta alasannya** — bukan didaftarkan supaya jumlahnya
+  terlihat banyak. Deskripsi paket, README, SKILL.md, entri katalog, dan
+  `lib/index.js` semuanya menyebut angka yang sama, dan `lib/index.js` punya
+  penjaga yang memperingatkan bila jumlahnya berubah tanpa dokumen ikut
+  diperbarui.
+  > **`iacr` dan `unpaywall` SEMPAT masuk daftar ini lalu dikeluarkan** setelah
+  > diuji ulang: `iacr` menjawab HTTP 200 dengan hasil yang bisa diurai, dan
+  > `unpaywall` menjawab HTTP 200 dengan DOI. Menganggap "bukan pencari kata
+  > kunci" sebagai "mati" adalah kekeliruan yang sudah dikoreksi.
+- **Kegagalan sumber tidak pernah disamarkan sebagai kekosongan.** Setiap
+  non-2xx melempar error beserta status HTTP-nya, dan kedua tool memisahkan
+  baris `GAGAL` dari baris `OK`. Ini perbaikan langsung atas kelemahan yang
+  terukur pada tool sejenis: konektornya mengembalikan daftar kosong untuk
+  SETIAP status != 200 tanpa mencatat apa pun, sehingga permintaan yang kena
+  batas laju terbaca sebagai "literatur ini tidak ada".
+- **CORE adalah satu-satunya sumber yang WAJIB berkunci.** Terukur: tanpa
+  `Bearer` ia menjawab HTTP 429 dengan body **kosong** — bukan 401. Karena itu
+  kunci yang hilang dilaporkan sebagai pesan yang bisa ditindaklanjuti, bukan
+  dibiarkan menjadi 429 yang membingungkan.
+- Tidak ada kunci API maupun alamat email yang dibawa paket ini.
+
+### Diuji
+
+- `node test/uji-sumber.mjs` — **8/8 lulus** melawan API dan halaman SUNGGUHAN;
+  **15 dari 16 sumber menjawab**. Dua kegagalan transien terlihat dan
+  **dilaporkan apa adanya**, bukan disembunyikan sebagai "0 hasil":
+  Semantic Scholar sempat 429 karena pengujian beruntun (pulih setelah 150
+  detik), dan PubMed Central sempat HTTP 500 `error forwarding request`
+  (batas laju E-utilities; sebelumnya 3 hasil di jalan yang sama).
+- `node test/uji-plugin.mjs` — **29/29 lulus** dengan `ctx` tiruan: dua tool
+  terdaftar, provider skill mengembalikan rank 450, frontmatter terurai
+  (deskripsi 348 huruf, di bawah batas katalog 500), dan kedua tool benar-benar
+  memanggil jaringan.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rasyid (rasyidmmz)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,50 @@
+# NOTICE
+
+## What this package is
+
+`dsh-paper-search` is an **independent implementation** for DeepSeek Harness. It
+contains no third-party source code. Every source connector in `lib/sources.js`
+is a small HTTP client written for this package, talking to public REST APIs and
+public web pages directly.
+
+## Upstream relationship
+
+This package was **inspired by** [`openags/paper-search-mcp`](https://github.com/openags/paper-search-mcp)
+(MIT licensed) and reuses its naming convention for optional credential
+environment variables (`PAPER_SEARCH_MCP_*`) so that a machine already set up
+for that tool needs no extra configuration. **No code from that project is
+included, vendored, or copied.** If you install the upstream CLI separately,
+this plugin will use it only as an optional extra source; it is never required.
+
+## Data sources and their terms
+
+Results come from public APIs and public web pages operated by third parties.
+Each keeps its own terms of use and rate limits. Users are responsible for
+complying with them. Specifically:
+
+| Source | Operator | Access |
+|---|---|---|
+| Crossref | Crossref (DOI registration agency) | public REST API |
+| OpenAlex | OurResearch | public REST API, "polite pool" email recommended |
+| DOAJ | Directory of Open Access Journals | public REST API |
+| Europe PMC | EMBL-EBI | public REST API |
+| PubMed | U.S. National Library of Medicine | public E-utilities API |
+| arXiv | Cornell University | public API, 1 request / 3 seconds requested |
+| Semantic Scholar | Allen Institute for AI | public API, key raises rate limits |
+| Garuda | Kemdiktisaintek, Republic of Indonesia | public web pages |
+| Sinta | Kemdiktisaintek, Republic of Indonesia | public web pages |
+| IOS OneSearch | Perpusnas, Republic of Indonesia | public web pages |
+| Moraref | Ministry of Religious Affairs, Republic of Indonesia | public web pages |
+
+## No bundled credentials
+
+This package ships **no API keys and no email addresses**. Any credential is
+read at runtime from the user's own configuration (plugin config, environment
+variable, or the upstream tool's `.env` file) and is never transmitted anywhere
+except to the service that issued it.
+
+## What this package does not do
+
+- It does not download or redistribute full-text PDFs.
+- It does not bypass paywalls or access controls.
+- It does not send queries to any service other than the ones listed above.

package/README.md

@@ -0,0 +1,151 @@
+# dsh-paper-search
+
+Literature search for **DeepSeek Harness**: sixteen sources behind one tool, all
+native HTTP — no external CLI, no Python package. Fourteen of them need no
+credential at all.
+
+Registered as the `paper-search` skill and two model tools (`paper_search`,
+`paper_status`).
+
+## Sources
+
+**International (13)** — official JSON APIs, except IACR which is parsed HTML:
+
+| id | Source | Notes |
+|---|---|---|
+| `crossref` | Crossref | DOI metadata across publishers, broadest coverage |
+| `openalex` | OpenAlex | metadata + abstracts; an email raises the rate limit |
+| `doaj` | DOAJ | open-access journals — includes many Indonesian journals |
+| `europepmc` | Europe PMC | biomedicine, full text for OA records |
+| `pubmed` | PubMed | biomedicine; two calls per search (esearch + esummary) |
+| `pmc` | PubMed Central | open-access full text; two calls per search |
+| `arxiv` | arXiv | preprints; the plugin self-paces to 1 request / 3 s per arXiv's TOU |
+| `semantic` | Semantic Scholar | a free key raises the rate limit |
+| `core` | CORE | open-access repository aggregator — **CORE_API_KEY required** |
+| `zenodo` | Zenodo | general repository: data, software, preprints |
+| `hal` | HAL | French open-access repository |
+| `iacr` | IACR ePrint | cryptology preprints |
+| `unpaywall` | Unpaywall | **DOI input, not keyword** — resolves a DOI to its open-access copy; **email required** |
+
+**Indonesian (3)** — parsed from public pages:
+
+| id | Source | Notes |
+|---|---|---|
+| `garuda` | Garuda (Kemdiktisaintek) | Indonesian journal articles |
+| `sinta` | Sinta (Kemdiktisaintek) | accredited **journals**, not articles |
+| `ios` | IOS OneSearch (Perpusnas) | Indonesian repository aggregator |
+
+### `sources: "all"` and the DOI-input source
+
+`unpaywall` answers only when the query **is a DOI**. So when you search with
+keywords, it is skipped rather than run and reported as an empty result — and
+the output says so:
+
+```
+CATATAN: unpaywall dilewati karena query ini bukan DOI — sumber itu memang
+mencari dengan DOI, bukan kata kunci.
+```
+
+Pass a DOI and it runs. Pass `sources: "unpaywall"` with keywords and it runs
+too, returning nothing — because that is genuinely how it behaves, and the
+output says that rather than pretending the source is broken.
+
+### Deliberately excluded, with the reason
+
+Every exclusion was measured on 2026-09-28. An always-empty source is worse than
+an absent one, so these are dropped rather than registered to look larger:
+
+| Source | Reason |
+|---|---|
+| `moraref` | landing page only, no parseable result markup (3,964 characters) |
+| `dblp` | API is behind bot protection — returns "Making sure you're not a bot!", not JSON |
+| `openaire` | test request **timed out at 30 s and again at 40 s** |
+| `biorxiv`, `medrxiv` | their API is **date-range** based, not keyword search |
+| `base` | OAI-PMH requires institutional IP registration (`Access denied for IP address …`) |
+| `citeseerx` | returns HTTP 404, then **hangs** until the request is killed |
+| `ssrn` | rejects ordinary requests with HTTP 403 |
+| `google_scholar` | bot detection active; a proxy is required |
+
+## Install
+
+```sh
+# from npm
+dsh plugin --profile <profile> add dsh-paper-search
+
+# or straight from the repository
+dsh plugin --profile <profile> add github:rasyidmmz/dsh-paper-search
+```
+
+The package ships a `dsh.bundle.patch`, so DSH installs its loader row
+automatically. **Do not also write an `id: paper-search` row by hand** — the
+loader throws `duplicate loader entry id` rather than warning.
+
+Restart DSH after installing.
+
+## Use
+
+```
+paper_search({ query: "machine learning" })
+paper_search({ query: "pendidikan karakter", sources: "indonesia" })
+paper_search({ query: "CRISPR", sources: "pubmed,europepmc,doaj", max_results: 10 })
+paper_search({ query: "digital literacy", open_access_only: true, year_from: 2020 })
+paper_status()                    # which sources answer right now
+paper_status({ probe: false })    # configuration only, no network
+```
+
+For Indonesian topics, **use Indonesian keywords**: `"pendidikan karakter"`
+returns real Indonesian journals, while the English equivalent returns
+international results that do not match the intent.
+
+## What makes the reporting honest
+
+Every result separates **sources that failed** from sources that answered:
+
+```
+  v Crossref            3 results  (2316 ms)
+  x Semantic Scholar    FAILED — HTTP 429 — {"message": "Too Many Requests...
+  v Garuda              3 results  (1428 ms)
+```
+
+A source that fails is never allowed to masquerade as "no results". This is not
+a detail: a widely-used tool in this space returns an empty list for *every*
+non-200 response with no error recorded at all, so a rate-limited request reads
+as "this literature does not exist". Here, the failure and its HTTP status are
+printed, and `paper_status` exists to prove liveness on demand.
+
+## Credentials (all optional)
+
+No key is bundled. Read order:
+
+1. plugin config in your DSH profile,
+2. environment variables `PAPER_SEARCH_MCP_<NAME>`, then `<NAME>`,
+3. the file `~/.config/paper-search-mcp/.env` (belonging to the upstream CLI).
+
+| Name | Purpose |
+|---|---|
+| `UNPAYWALL_EMAIL` | any email — used as the Crossref/OpenAlex "polite pool" contact |
+| `OPENALEX_EMAIL` | same, OpenAlex only |
+| `SEMANTIC_SCHOLAR_API_KEY` | raises Semantic Scholar rate limits |
+| `DOAJ_API_KEY` | raises DOAJ's hourly limit |
+| `CORE_API_KEY` | **required for the `core` source** — without it CORE answers HTTP 429 with an empty body |
+
+Fourteen of the sixteen sources work with no credential at all; keys raise rate
+limits and stability. **Two are exceptions, and each is reported as a clear,
+actionable failure rather than a confusing 429:**
+
+- `core` needs `CORE_API_KEY`.
+- `unpaywall` needs an email (any real address) — it also needs a DOI as input.
+
+## What this package does not do
+
+- It does not download or redistribute full-text PDFs.
+- It does not bypass paywalls or access controls.
+- It does not call any service other than the ten listed above.
+- It does not require or install `paper-search-mcp`. If that CLI happens to be
+  installed, you can use it for its additional sources (CORE, Zenodo, HAL,
+  SSRN, Unpaywall, OpenAIRE, CiteSeerX, BASE) — this plugin never depends on it.
+
+## Licence and attribution
+
+MIT — see [LICENSE](LICENSE). Attribution and source terms are in
+[NOTICE.md](NOTICE.md).

package/cordis.patch.yml

@@ -0,0 +1,17 @@
+# Patch bundle dsh-paper-search.
+#
+# Bentuk ini DISALIN dari bundle yang sudah terbukti terpasang di profil
+# (`dsh-ai-memory/cordis.patch.yml`) — bukan dikarang:
+#
+#     - insert:
+#         - id: <id>
+#           name: <nama paket npm>
+#
+# `id` harus UNIK. Loader melempar `duplicate loader entry id` bila id yang sama
+# muncul dua kali, dan itu terjadi SEBELUM aplikasi sempat memperingatkan.
+#
+# `path` TIDAK ditulis di sini: entri `insert` hanya menyebut nama paket, dan DSH
+# menyelesaikan berkas masuknya dari `main`/`exports` package.json paket.
+- insert:
+    - id: paper-search
+      name: dsh-paper-search