dsh-paper-search 0.1.0

package/lib/index.js

@@ -0,0 +1,381 @@
+// lib/index.js — plugin DSH `dsh-paper-search`.
+//
+// TIGA HAL YANG DILAKUKAN PLUGIN INI:
+//   1. mendaftarkan skill `paper-search` lewat `ctx.get('skills')`, di rank 450
+//      supaya KALAH dari berkas di `~/.dsh/skills` (rank 400) — jadi suntingan
+//      pengguna selalu menang, dan registrasi ini hanya cadangan untuk keadaan
+//      provider preset mati (mis. preset "Creator mode");
+//   2. tool `paper_search` — pencarian literatur lintas sumber;
+//   3. tool `paper_status` — "doctor": sumber mana yang menjawab dan kredensial
+//      mana yang terbaca. Ini jawaban langsung atas masalah yang berulang di
+//      tool sejenis: kegagalan yang menyamar jadi "0 hasil".
+//
+// KREDENSIAL: tidak ada kunci yang dibawa paket ini. Urutan pembacaannya
+//   1. config plugin (dari profil pengguna)
+//   2. variabel lingkungan PAPER_SEARCH_MCP_<NAMA>, lalu <NAMA>
+//   3. berkas ~/.config/paper-search-mcp/.env  (milik CLI upstream)
+// Langkah 3 ada supaya mesin yang sudah disetel untuk `paper-search-mcp` tidak
+// perlu konfigurasi ulang.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { SUMBER, ID_SUMBER, ID_INTERNASIONAL, ID_INDONESIA, searchSource, dedup, cariSumber, apakahDoi } from './sources.js';
+
+export const name = 'paper-search';
+// `skills` dan `fs` sengaja TIDAK di-inject: keduanya opsional, dibaca lewat
+// ctx.get(). Tanpa itu plugin tetap harus mendaftarkan tool-nya.
+export const inject = ['tools'];
+
+const DIR_PAKET = dirname(dirname(fileURLToPath(import.meta.url)));
+const BERKAS_SKILL = join(DIR_PAKET, 'skills', 'paper-search', 'SKILL.md');
+const PREFIX = 'PAPER_SEARCH_MCP_';
+
+// ── Kredensial ───────────────────────────────────────────────────────────────
+
+/** Baca .env milik CLI upstream, kalau ada. Tidak pernah melempar. */
+function bacaEnvUpstream() {
+  const keluaran = {};
+  try {
+    const p = join(homedir(), '.config', 'paper-search-mcp', '.env');
+    if (!existsSync(p)) return keluaran;
+    for (const baris of readFileSync(p, 'utf8').split(/\r?\n/)) {
+      const m = /^\s*([A-Z0-9_]+)\s*=\s*(.*)$/.exec(baris);
+      if (m && m[2].trim()) keluaran[m[1]] = m[2].trim();
+    }
+  } catch {
+    // Berkas tidak terbaca = tidak ada kredensial dari jalur ini. Bukan galat.
+  }
+  return keluaran;
+}
+
+function buatPembacaKredensial(config) {
+  const dariBerkas = bacaEnvUpstream();
+  return function ambil(nama) {
+    if (config && config[nama]) return { nilai: String(config[nama]), dari: 'config plugin' };
+    const env = process.env[PREFIX + nama] ?? process.env[nama];
+    if (env) return { nilai: String(env), dari: 'variabel lingkungan' };
+    if (dariBerkas[PREFIX + nama]) return { nilai: dariBerkas[PREFIX + nama], dari: '.env upstream' };
+    if (dariBerkas[nama]) return { nilai: dariBerkas[nama], dari: '.env upstream (nama lama)' };
+    return { nilai: null, dari: null };
+  };
+}
+
+/** Email apa pun yang tersedia — dipakai untuk "polite pool" Crossref/OpenAlex. */
+function emailPolite(ambil) {
+  return ambil('UNPAYWALL_EMAIL').nilai || ambil('OPENALEX_EMAIL').nilai || null;
+}
+
+// ── Pencarian ────────────────────────────────────────────────────────────────
+
+/** Terjemahkan pilihan pengguna menjadi daftar id sumber. */
+function pilihSumber(permintaan) {
+  const t = String(permintaan ?? '').trim().toLowerCase();
+  if (!t || t === 'all' || t === 'semua' || t === '*') return { sah: ID_SUMBER, takDikenal: [], eksplisit: false };
+  if (t === 'international' || t === 'internasional') return { sah: ID_INTERNASIONAL, takDikenal: [], eksplisit: false };
+  if (t === 'indonesia' || t === 'lokal') return { sah: ID_INDONESIA, takDikenal: [], eksplisit: false };
+  const sah = [];
+  const takDikenal = [];
+  for (const id of t.split(/[,\s]+/).filter(Boolean)) (cariSumber(id) ? sah : takDikenal).push(id);
+  return { sah, takDikenal, eksplisit: true };
+}
+
+async function jalankanPencarian(args, kredensial) {
+  const query = String(args?.query ?? '').trim();
+  if (!query) throw new Error('parameter "query" wajib diisi');
+
+  const queryDoi = apakahDoi(query);
+  const pilihan = pilihSumber(args?.sources);
+  if (pilihan.sah.length === 0) {
+    throw new Error(`tidak ada sumber yang sah. Yang tersedia: ${ID_SUMBER.join(', ')}`);
+  }
+
+  // Sumber ber-input DOI (unpaywall) hanya ikut kalau query-nya memang DOI.
+  // Kalau diminta EKSPLISIT, ia tetap dijalankan — hasilnya kosong dan itu
+  // dijelaskan kepada pengguna, bukan dibuang diam-diam.
+  const ids = [];
+  const dilewati = [];
+  for (const id of pilihan.sah) {
+    if (!queryDoi && cariSumber(id)?.input === 'doi' && !pilihan.eksplisit) { dilewati.push(id); continue; }
+    ids.push(id);
+  }
+  if (ids.length === 0) {
+    throw new Error(
+      `semua sumber yang dipilih ber-input DOI (${dilewati.join(', ')}), sedangkan query ini bukan DOI. `
+      + 'Sertakan sumber lain, atau berikan DOI-nya.',
+    );
+  }
+
+  const rows = Math.min(Math.max(Number(args?.max_results) || 5, 1), 50);
+  const email = emailPolite(kredensial);
+  const opsi = {
+    rows,
+    email,
+    apiKey: kredensial('SEMANTIC_SCHOLAR_API_KEY').nilai,
+    doajApiKey: kredensial('DOAJ_API_KEY').nilai,
+    coreApiKey: kredensial('CORE_API_KEY').nilai,
+  };
+
+  const perSumber = await Promise.all(ids.map((id) => searchSource(id, query, opsi)));
+
+  let papers = dedup(perSumber.flatMap((h) => h.papers));
+  if (args?.open_access_only) papers = papers.filter((p) => p.openAccess);
+  const tahun = Number(args?.year_from);
+  if (Number.isFinite(tahun) && tahun > 1500) papers = papers.filter((p) => !p.year || p.year >= tahun);
+
+  return { query, rows, ids, takDikenal: pilihan.takDikenal, dilewati, perSumber, papers };
+}
+
+/**
+ * Satu baris status sumber — DIPAKAI KEDUA TOOL supaya penandaannya identik.
+ * Sebelumnya tool pencarian memakai "v/x" dan tool status memakai "✓/✗", dan
+ * ketidakcocokan itu membuat uji sendiri gagal. Teks polos juga lebih aman di
+ * terminal mana pun.
+ */
+function barisSumber(label, h, keterangan = '') {
+  const l = String(label).padEnd(18);
+  return h.error
+    ? `  GAGAL ${l} ${keterangan}${h.error}`
+    : `  OK    ${l} ${keterangan}${String(h.papers.length).padStart(3)} hasil  (${h.ms} ms)`;
+}
+
+function formatHasil(hasil) {
+  const { perSumber, papers } = hasil;
+  const gagal = perSumber.filter((h) => h.error);
+  const baris = [];
+
+  baris.push(`query: ${hasil.query}`);
+  baris.push(`${perSumber.length} sumber dicari · ${perSumber.length - gagal.length} menjawab · ${papers.length} paper unik setelah dedup`);
+  if (hasil.takDikenal?.length) baris.push(`PERHATIAN: sumber tidak dikenal (diabaikan): ${hasil.takDikenal.join(', ')}`);
+  if (hasil.dilewati?.length) {
+    baris.push(`CATATAN: ${hasil.dilewati.join(', ')} dilewati karena query ini bukan DOI — sumber itu memang mencari dengan DOI, bukan kata kunci.`);
+  }
+  baris.push('');
+  baris.push('per sumber:');
+  for (const h of [...perSumber].sort((a, b) => (b.papers.length - a.papers.length) || a.id.localeCompare(b.id))) {
+    const s = cariSumber(h.id);
+    const jenis = `${s?.kind ?? ''}${s?.input === 'doi' ? '/doi' : ''}`.padEnd(8);
+    baris.push(barisSumber(s?.label ?? h.id, h, jenis));
+  }
+
+  if (gagal.length) {
+    baris.push('');
+    baris.push('PERHATIAN: sumber bertanda GAGAL di atas HARUS disebutkan saat melaporkan hasil —');
+    baris.push('jangan menyimpulkan "tidak ada literatur" dari sumber yang gagal.');
+  }
+
+  baris.push('');
+  if (papers.length === 0) {
+    baris.push('TIDAK ADA hasil yang lolos filter.');
+    baris.push('Sebelum menyimpulkan "tidak ada literatur": ulangi sekali, lalu coba sumber lain.');
+    return baris.join('\n');
+  }
+
+  papers.slice(0, 40).forEach((p, i) => {
+    const penulis = p.authors.length ? p.authors.slice(0, 3).join('; ') + (p.authors.length > 3 ? ' dkk' : '') : '(penulis tidak dilaporkan)';
+    baris.push(`${i + 1}. ${p.title}`);
+    baris.push(`   ${p.year ?? '?'} · ${p.journal ?? 'jurnal tidak dilaporkan'} · ${penulis}`);
+    baris.push(`   sumber: ${p.sources.join(', ')}${p.openAccess ? ' · akses terbuka' : ''}`);
+    if (p.doi) baris.push(`   doi: ${p.doi}`);
+    else if (p.url) baris.push(`   url: ${p.url}`);
+    if (p.abstract) baris.push(`   abstrak: ${p.abstract}`);
+  });
+  if (papers.length > 40) baris.push(`… dan ${papers.length - 40} lagi (persempit query atau turunkan max_results).`);
+  return baris.join('\n');
+}
+
+// ── Tool ─────────────────────────────────────────────────────────────────────
+
+function toolSearch(kredensial) {
+  return {
+    name: 'paper_search',
+    description:
+      'Cari literatur ilmiah dari 13 sumber internasional (Crossref, OpenAlex, DOAJ, Europe PMC, PubMed, PubMed Central, arXiv, Semantic Scholar, CORE, Zenodo, HAL, IACR ePrint, Unpaywall) dan 3 portal jurnal Indonesia (Garuda, Sinta, IOS OneSearch) sekaligus, lalu buang duplikatnya berdasarkan DOI/judul. '
+      + 'Semua native lewat HTTP — tidak butuh CLI atau paket luar. '
+      + 'Pakai untuk: mencari paper/jurnal, penelitian terdahulu, literatur Indonesia, atau melacak DOI. '
+      + 'Keluaran memisahkan sumber yang GAGAL dari yang menjawab, jadi "0 hasil" dari satu sumber tidak boleh disimpulkan sebagai "tidak ada literatur".',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Kata kunci. Untuk topik Indonesia pakai kata kunci bahasa Indonesia — hasilnya jauh lebih relevan.' },
+        sources: { type: 'string', description: `Daftar id dipisah koma, atau "all" / "international" / "indonesia". Id yang tersedia: ${ID_SUMBER.join(', ')}. Bawaan: semua.` },
+        max_results: { type: 'number', description: 'Hasil per sumber (1-50, bawaan 5).' },
+        open_access_only: { type: 'boolean', description: 'Hanya kembalikan paper akses-terbuka (bila sumber melaporkannya).' },
+        year_from: { type: 'number', description: 'Hanya paper dengan tahun >= nilai ini.' },
+      },
+      required: ['query'],
+    },
+    execute: async (args) => {
+      const hasil = await jalankanPencarian(args ?? {}, kredensial);
+      return formatHasil(hasil);
+    },
+  };
+}
+
+function toolStatus(kredensial) {
+  return {
+    name: 'paper_status',
+    description:
+      'Periksa kesehatan pencarian literatur: sumber mana yang benar-benar MENJAWAB sekarang (bukan sekadar terdaftar), kredensial mana yang terbaca dan dari mana asalnya, serta apakah CLI paper-search-mcp opsional terpasang. '
+      + 'Pakai sebelum melaporkan "tidak ada hasil", atau saat pengguna bertanya kenapa pencarian kosong. '
+      + 'Secara bawaan ia mengirim satu permintaan kecil ke setiap sumber.',
+    parameters: {
+      type: 'object',
+      properties: {
+        probe: { type: 'boolean', description: 'Kirim satu permintaan kecil ke tiap sumber untuk membuktikan ia hidup (bawaan true). Setel false untuk memeriksa konfigurasi saja tanpa jaringan.' },
+        sources: { type: 'string', description: 'Batasi pemeriksaan ke sebagian sumber (id dipisah koma). Bawaan: semua.' },
+      },
+      required: [],
+    },
+    execute: async (args) => {
+      const probe = args?.probe !== false;
+      const barisPilihan = pilihSumber(args?.sources);
+      const ids = barisPilihan.sah.length ? barisPilihan.sah : ID_SUMBER;
+      const keluar = [];
+      keluar.push('== kredensial ==');
+      for (const nama of ['UNPAYWALL_EMAIL', 'OPENALEX_EMAIL', 'SEMANTIC_SCHOLAR_API_KEY', 'DOAJ_API_KEY', 'CORE_API_KEY']) {
+        const k = kredensial(nama);
+        const nilaiTampil = k.nilai
+          ? (nama.endsWith('EMAIL') ? k.nilai : `terisi (${k.nilai.length} huruf)`)
+          : 'KOSONG';
+        keluar.push(`  ${nama.padEnd(30)} ${nilaiTampil}${k.dari ? `  ← ${k.dari}` : ''}`);
+      }
+      keluar.push('  catatan: OpenAIRE dan CiteSeerX tidak dipakai plugin ini; IEEE dan ACM tidak dipakai karena konektornya di upstream masih kerangka.');
+
+      keluar.push('');
+      keluar.push('== sumber ==');
+      const email = emailPolite(kredensial);
+      const opsi = { rows: 1, email, apiKey: kredensial('SEMANTIC_SCHOLAR_API_KEY').nilai, doajApiKey: kredensial('DOAJ_API_KEY').nilai, coreApiKey: kredensial('CORE_API_KEY').nilai };
+      for (const id of ids) {
+        const s = cariSumber(id);
+        const jenis = `${s.kind}${s.input === 'doi' ? '/doi' : ''}`.padEnd(8);
+        if (!probe) {
+          keluar.push(`  ?     ${s.label.padEnd(18)} ${jenis} terdaftar (probe dimatikan)`);
+          continue;
+        }
+        // Sumber ber-input DOI diuji dengan DOI sungguhan — kalau diuji dengan
+        // kata kunci ia selalu 0 dan itu terbaca seolah sumbernya rusak.
+        const kueri = s.input === 'doi' ? '10.1038/s41580-023-00697-6' : 'literature';
+        const h = await searchSource(id, kueri, opsi);
+        keluar.push(barisSumber(s.label, h, jenis));
+      }
+
+      keluar.push('');
+      keluar.push('== CLI paper-search-mcp (opsional) ==');
+      keluar.push(`  Plugin ini TIDAK memerlukannya — ${SUMBER.length} sumber di atas sudah native.`);
+      keluar.push('  Kalau terpasang, ia menambah sumber lain (CORE, Zenodo, HAL, SSRN, Unpaywall, dll).');
+      keluar.push('  Pasang: uv tool install --force "git+https://github.com/openags/paper-search-mcp"');
+      return keluar.join('\n');
+    },
+  };
+}
+
+// ── Skill ────────────────────────────────────────────────────────────────────
+
+/** Pengurai frontmatter datar — cukup untuk SKILL.md milik paket ini. */
+function uraiFrontmatter(mentah) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(mentah);
+  if (!m) return null;
+  const blok = m[1];
+  const badan = mentah.slice(m[0].length).trim();
+  const ambil = (kunci) => {
+    const a = new RegExp(`^${kunci}:\\s*"([^"]*)"`, 'm').exec(blok);
+    if (a) return a[1].trim();
+    const b = new RegExp(`^${kunci}:\\s*(.+)$`, 'm').exec(blok);
+    return b ? b[1].trim() : '';
+  };
+  const nama = ambil('name');
+  if (!nama) return null;
+  return {
+    nama,
+    deskripsi: ambil('description'),
+    kapanPakai: ambil('whenToUse'),
+    // Kebijakan invocation dihormati DARI BERKAS, jangan dipaksakan `true`.
+    modelInvocable: ambil('disable-model-invocation').toLowerCase() !== 'true',
+    userInvocable: ambil('user-invocable').toLowerCase() !== 'false',
+    badan,
+  };
+}
+
+function daftarkanSkill(ctx, notes) {
+  const skills = ctx.get('skills');
+  if (!skills || typeof skills.registerProvider !== 'function') {
+    notes.push('service skills tidak tersedia — skill hanya terbaca dari berkas');
+    return;
+  }
+  const baca = async () => {
+    try {
+      const fsSvc = ctx.get('fs');
+      let mentah;
+      if (fsSvc && typeof fsSvc.readText === 'function') {
+        mentah = await fsSvc.readText(await fsSvc.resolve(BERKAS_SKILL));
+      } else {
+        if (!existsSync(BERKAS_SKILL)) return null;
+        mentah = readFileSync(BERKAS_SKILL, 'utf8');
+      }
+      const isi = uraiFrontmatter(mentah);
+      // Nama di frontmatter harus cocok — kalau tidak, ini bukan skill kita.
+      return isi && isi.nama === 'paper-search' ? isi : null;
+    } catch {
+      return null;
+    }
+  };
+  const ringkas = (isi) => ({
+    name: isi.nama,
+    description: isi.deskripsi || '',
+    ...(isi.kapanPakai ? { whenToUse: isi.kapanPakai } : {}),
+    invocation: { modelInvocable: isi.modelInvocable, userInvocable: isi.userInvocable },
+    source: 'runtime',
+    provider: 'paper-search-runtime',
+    // Rank 450: DI ATAS 400 (~/.dsh/skills) supaya kalah dari berkas yang
+    // disunting pengguna, tetapi masih menang atas user-agents/bundled (500/600).
+    rank: 450,
+    locator: { berkas: BERKAS_SKILL },
+  });
+
+  ctx.effect(() => skills.registerProvider(() => ({
+    name: 'paper-search-runtime',
+    // Dibaca SETIAP kali (tidak di-cache) supaya suntingan SKILL.md langsung
+    // terpakai tanpa restart DSH.
+    list: async () => {
+      const isi = await baca();
+      return isi ? [ringkas(isi)] : [];
+    },
+    get: async (kandidat) => {
+      if (kandidat?.name !== 'paper-search') return undefined;
+      const isi = await baca();
+      if (!isi) return undefined;
+      return {
+        ...ringkas(isi),
+        content: isi.badan,
+        resourceBase: { kind: 'directory', path: dirname(BERKAS_SKILL) },
+      };
+    },
+  })));
+  notes.push('skill paper-search terdaftar di layer global (rank 450, cadangan)');
+}
+
+// ── apply ────────────────────────────────────────────────────────────────────
+
+export function apply(ctx, config) {
+  const notes = [];
+  const kredensial = buatPembacaKredensial(config);
+
+  ctx.effect(() => ctx.tools.register(toolSearch(kredensial)));
+  notes.push('tool paper_search terdaftar');
+  ctx.effect(() => ctx.tools.register(toolStatus(kredensial)));
+  notes.push('tool paper_status terdaftar');
+
+  daftarkanSkill(ctx, notes);
+
+  if (SUMBER.length !== 16) {
+    // Penjaga: deskripsi paket, README, SKILL.md, CHANGELOG, dan entri katalog
+    // semuanya menyebut JUMLAH sumber. Kalau daftar ini berubah, kelimanya harus
+    // ikut — dan penilai katalog memang mencocokkan angka di deskripsi ke kode.
+    notes.push(`PERINGATAN: jumlah sumber ${SUMBER.length}, bukan 16 — perbarui deskripsi package.json, README, SKILL.md, CHANGELOG, dan entri katalog`);
+  }
+  notes.push(`${ID_INTERNASIONAL.length} sumber internasional + ${ID_INDONESIA.length} sumber Indonesia`);
+  return notes.join(' · ');
+}