@clazic/urban 0.2.8 → 0.2.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clazic/urban",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "도시계획연구 보고서 자동 수집·지식베이스 데몬",
   "type": "module",
   "engines": {

package/scripts/postinstall.js

@@ -39,14 +39,20 @@ try {
     if (installResult.ok) {
       console.log(`[urban] 데몬 등록 완료: ${installResult.message}`);
       const startResult = await startDaemon();
-      console.log(`[urban] 데몬 시작: ${startResult.message}`);
-      console.log(`\n[urban] 설치 완료 → http://localhost:${URBAN_PORT}\n`);
+      if (startResult.ok) {
+        console.log(`[urban] 데몬 시작 완료`);
+        console.log(`\n✅ 설치 완료 → http://localhost:${URBAN_PORT}\n`);
+      } else {
+        console.warn(`[urban] 데몬 등록은 완료됐지만 시작 실패: ${startResult.message}`);
+        console.warn(`\n👉 시작하려면: urban start\n`);
+      }
     } else {
-      console.warn(`[urban] 데몬 자동 등록 실패 — 'urban install && urban start' 로 수동 시작`);
-      console.warn(`       원인: ${installResult.message}`);
+      console.warn(`\n⚠️  데몬 자동 등록 실패 (원인: ${installResult.message})`);
+      console.warn(`👉 설치 후 수동으로 실행하세요: urban start\n`);
     }
   } catch (err) {
-    console.warn(`[urban] 데몬 자동 시작 건너뜀 — 'urban install && urban start' 로 수동 시작`);
+    console.warn(`\n⚠️  데몬 자동 시작 건너뜀 (원인: ${err.message})`);
+    console.warn(`👉 설치 후 수동으로 실행하세요: urban start\n`);
   }
 } catch (err) {
   // postinstall 전체 실패해도 npm install은 성공으로 처리

package/src/agent/skills/_dbpia-access-filter.js

@@ -0,0 +1,109 @@
+/**
+ * DBpia 검색 결과 ↔ access cache 기반 필터/업서트 공용 모듈
+ *
+ * 정책:
+ *  - strict=true  : cache status='ok' 인 항목만 통과. miss(unknown) 및 부정 상태 숨김
+ *  - strict=false : cache status='ok' 또는 miss(unknown) 통과. 부정 상태만 숨김
+ *  - HIDDEN_STATUSES 의 부정 상태(license_out / external_link / thesis_unsupported /
+ *    publisher_disallow / link_missing)는 **토글 상태와 무관하게 항상 숨김**
+ */
+
+/** 검색 결과에서 항상 숨겨야 할 상태 */
+export const HIDDEN_STATUSES = new Set([
+  'license_out',
+  'external_link',
+  'thesis_unsupported',
+  'publisher_disallow',
+  'link_missing',
+]);
+
+/** error.reason enum → cache status enum 매핑 */
+export function reasonToStatus(reason) {
+  switch (reason) {
+    case 'license_out_of_scope': return 'license_out';
+    case 'external_link':        return 'external_link';
+    case 'thesis_unsupported':   return 'thesis_unsupported';
+    case 'publisher_disallow':   return 'publisher_disallow';
+    case 'link_missing':         return 'link_missing';
+    case 'session_expired':      return null;  // 일시적 오류 → cache 적재 안 함
+    case 'unknown_error':        return null;  // 네트워크 등 일시 오류
+    default:                     return null;
+  }
+}
+
+/**
+ * 검색 결과 필터링 — cache 조회 후 strict 모드에 따라 통과/차단 결정
+ *
+ * @param {Array} items  normalizeDbpiaItem 결과 배열 (각 항목에 nodeId 필요)
+ * @param {{db, strict, b2bId}} ctx
+ * @returns {Array} accessStatus 필드가 추가된 필터링 결과
+ */
+export function filterByAccessCache(items, { db, strict = true, b2bId = 'ICST00001014' }) {
+  if (!db || !Array.isArray(items) || items.length === 0) return items;
+
+  const nodeIds = items.map(it => it.nodeId).filter(Boolean);
+  if (nodeIds.length === 0) return items;
+
+  const placeholders = nodeIds.map(() => '?').join(',');
+  let rows = [];
+  try {
+    rows = db.prepare(
+      `SELECT node_id, status FROM dbpia_access_cache
+       WHERE b2b_id = ? AND node_id IN (${placeholders})`
+    ).all(b2bId, ...nodeIds);
+  } catch (e) {
+    console.warn('[dbpia-access-filter] cache 조회 실패:', e.message);
+    return items;  // cache 미초기화 등 오류 시 pass-through
+  }
+
+  const statusByNode = new Map(rows.map(r => [r.node_id, r.status]));
+
+  return items
+    .map(it => ({ ...it, accessStatus: statusByNode.get(it.nodeId) || 'unknown' }))
+    .filter(it => {
+      // 항상 숨김: 부정 상태
+      if (HIDDEN_STATUSES.has(it.accessStatus)) return false;
+      // strict 모드: ok 만 통과 (unknown 도 숨김)
+      if (strict && it.accessStatus !== 'ok') return false;
+      return true;
+    });
+}
+
+/**
+ * access_cache 에 판정 결과 upsert
+ *
+ * @param {Database} db
+ * @param {{nodeId, b2bId?, status, reason?, contentType?, bytes?}} entry
+ */
+export function upsertAccessCache(db, { nodeId, b2bId = 'ICST00001014', status, reason, contentType, bytes }) {
+  if (!db || !nodeId || !status) return;
+  try {
+    db.prepare(`
+      INSERT INTO dbpia_access_cache (node_id, b2b_id, status, reason, content_type, bytes, checked_at, retries)
+      VALUES (?, ?, ?, ?, ?, ?, ?, 1)
+      ON CONFLICT(node_id, b2b_id) DO UPDATE SET
+        status = excluded.status,
+        reason = excluded.reason,
+        content_type = excluded.content_type,
+        bytes = excluded.bytes,
+        checked_at = excluded.checked_at,
+        retries = dbpia_access_cache.retries + 1
+    `).run(nodeId, b2bId, status, reason ?? null, contentType ?? null, bytes ?? null, Date.now());
+  } catch (e) {
+    console.warn('[dbpia-access-filter] upsert 실패:', e.message);
+  }
+}
+
+/**
+ * cache row 수 조회 — warmupMode 결정용
+ * @returns {number}
+ */
+export function countAccessCacheRows(db, b2bId = 'ICST00001014') {
+  if (!db) return 0;
+  try {
+    const row = db.prepare('SELECT COUNT(*) AS c FROM dbpia_access_cache WHERE b2b_id = ?').get(b2bId);
+    return row?.c || 0;
+  } catch {
+    return 0;
+  }
+}

package/src/agent/skills/_normalize.js

@@ -0,0 +1,228 @@
+/**
+ * 공통 텍스트 정규화 유틸 (prism-dl normalizer.js ESM 포팅)
+ */
+
+/** 파이프라인에서 지원하는 파일 확장자 목록 */
+export const SUPPORTED_EXTS = new Set(['.pdf', '.hwp', '.hwpx', '.docx', '.xlsx', '.jpg', '.jpeg', '.png', '.zip']);
+
+/**
+ * 파일명 기준 지원 여부 확인
+ * @param {string} [fileName]
+ * @returns {boolean} - 파일명이 없거나 알 수 없으면 true (허용), 명확히 미지원 확장자면 false
+ */
+export function isSupportedFile(fileName) {
+  if (!fileName) return true;
+  const dot = fileName.lastIndexOf('.');
+  if (dot < 0) return true; // 확장자 없으면 일단 허용 (다운로드 후 판단)
+  const ext = fileName.slice(dot).toLowerCase();
+  return SUPPORTED_EXTS.has(ext);
+}
+
+/** 외부 검색 결과 UI에 표시 허용되는 확장자 (파이프라인 지원보다 엄격) */
+export const EXTERNAL_VISIBLE_EXTS = new Set(['.pdf', '.hwp', '.hwpx', '.docx', '.doc', '.zip']);
+
+/**
+ * 외부 검색 결과 표시 가능 여부. fileName 불명 시 false (엄격).
+ */
+export function isExternalVisibleFile(fileName) {
+  if (!fileName) return false;
+  const dot = fileName.lastIndexOf('.');
+  if (dot < 0) return false;
+  return EXTERNAL_VISIBLE_EXTS.has(fileName.slice(dot).toLowerCase());
+}
+
+export function stripHighlightTags(value) {
+  return String(value || '').replace(/<!HS>|<!HE>/g, '');
+}
+
+export function decodeHtmlEntities(value) {
+  let output = String(value || '');
+  const named = { nbsp: ' ', amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", '#39': "'" };
+  output = output.replace(/&([a-zA-Z0-9#]+);/g, (match, entity) => {
+    if (entity.startsWith('#x')) {
+      const n = parseInt(entity.slice(2), 16);
+      return isNaN(n) ? match : String.fromCodePoint(n);
+    }
+    if (entity.startsWith('#')) {
+      const n = parseInt(entity.slice(1), 10);
+      return isNaN(n) ? match : String.fromCodePoint(n);
+    }
+    return Object.prototype.hasOwnProperty.call(named, entity) ? named[entity] : match;
+  });
+  return output;
+}
+
+export function htmlToText(value) {
+  return String(value || '')
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<\/p>/gi, '\n')
+    .replace(/<!--[\s\S]*?-->/g, ' ')             // HTML 주석 제거
+    .replace(/<[^>]*>/g, ' ')                      // 정상 태그 제거
+    .replace(/<\/?[a-zA-Z][^<>]*$/g, ' ');         // 끝이 잘린 태그 꼬리 제거
+}
+
+export function cleanWhitespace(value) {
+  return String(value || '')
+    .replace(/\r/g, '\n')
+    .replace(/\t/g, ' ')
+    .replace(/[ \u00A0]+/g, ' ')
+    .replace(/\n{3,}/g, '\n\n')
+    .replace(/[ \n]+$/g, '')
+    .replace(/^[ \n]+/g, '');
+}
+
+export function toPlainText(value) {
+  return cleanWhitespace(decodeHtmlEntities(htmlToText(stripHighlightTags(value))));
+}
+
+export function inferYear(value) {
+  const candidates = [
+    value?.PBLCN_YR, value?.FRST_REG_DT, value?.DATE,
+    value?.RSCH_END_YMD, value?.RSCH_BGNG_YMD,
+  ].filter(Boolean).map(String);
+
+  for (const c of candidates) {
+    const m = c.match(/(19|20)\d{2}/);
+    if (m) return m[0];
+  }
+  return '미상';
+}
+
+const PARENT_INSTITUTIONS = [
+  '서울특별시', '부산광역시', '대구광역시', '인천광역시', '광주광역시',
+  '대전광역시', '울산광역시', '세종특별자치시', '경기도', '강원특별자치도',
+  '충청북도', '충청남도', '전북특별자치도', '전라남도', '경상북도', '경상남도', '제주특별자치도',
+];
+
+export function normalizeInstitution(name) {
+  const stripped = String(name || '').replace(/\s+/g, '');
+  for (const p of PARENT_INSTITUTIONS) {
+    if (stripped.startsWith(p)) return p;
+  }
+  return name;
+}
+
+/** PRISM API 응답 항목 → NormalizedItem */
+export function normalizePrismItem(item, query) {
+  return {
+    docid: `prism-${item.DOCID}`,
+    source: 'prism',
+    query,
+    title: toPlainText(item.ASMT_NM) || '제목없음',
+    institution: toPlainText(item.INST_NM) || '기관미상',
+    institutionId: String(item.JRSD_INST_GRNT_NO || ''),
+    year: inferYear(item),
+    fileName: toPlainText(item.FILE_NM) || '파일명없음',
+    fileSize: Number(item.FILE_SZ || 0),
+    keywords: toPlainText(item.KYWD_CN),
+    outline: toPlainText(item.ASMT_OTLN),
+    summary: toPlainText(item.THSS_SMRY_CN),
+    contentPreview: toPlainText(item.FILE_CONTENT).slice(0, 800),
+    // 다운로드 시 필요한 PRISM 전용 필드
+    asmtId: String(item.ASMT_ID || ''),
+    fileTypeCd: String(item.FILE_TYPE_CD || ''),
+    fileSn: String(item.FILE_SN || ''),
+    fileWkky: String(item.FILE_WKKY || ''),
+    pdfTrsfYn: String(item.PDF_TRSF_YN || 'Y'),
+  };
+}
+
+/** DBpia 검색 결과 → NormalizedItem
+ * 실제 응답 필드 (2026-04-19 확인):
+ *   nodeId, nodeTitle (<!HS>/<!HE> 마커 포함), abstractText,
+ *   publishYymm("YYYY.MM"), authors[]{autrNm}, iprdNm, plctNm,
+ *   labels.nodeType, externalLink, searchKeywords[]
+ */
+export function normalizeDbpiaItem(item, query) {
+  const nodeId = String(item.nodeId || '').trim();
+  const docid  = nodeId ? `dbpia-${nodeId}` : `dbpia-unknown-${Date.now()}`;
+
+  const title = toPlainText(item.nodeTitle || '') || '제목없음';
+
+  const authors = Array.isArray(item.authors)
+    ? item.authors.map(a => toPlainText(a.autrNm || '')).filter(Boolean)
+    : [];
+
+  const rawOrg  = item.iprdNm || item.plctNm || '';
+  const institution = normalizeInstitution(toPlainText(rawOrg)) || '학술DB';
+
+  // publishYymm: "2016.01" → year "2016"
+  const year = String(item.publishYymm || '').slice(0, 4) || '미상';
+
+  const keywords = Array.isArray(item.searchKeywords)
+    ? item.searchKeywords.map(k => toPlainText(k)).filter(Boolean).join(', ')
+    : '';
+
+  const abstract = toPlainText(item.abstractText || '');
+  const nodeType = item.labels?.nodeType ?? '';
+  const fileName = `${year !== '미상' ? `(${year}) ` : ''}${title}.pdf`;
+  const url      = nodeId
+    ? `https://www.dbpia.co.kr/journal/articleDetail?nodeId=${nodeId}`
+    : '';
+
+  return {
+    docid,
+    source: 'dbpia',
+    query,
+    title,
+    institution,
+    institutionId: '',
+    year,
+    fileName,
+    fileSize: 0,
+    keywords,
+    outline: abstract,
+    summary: abstract.slice(0, 800),
+    contentPreview: abstract.slice(0, 800),
+    // DBpia 전용 필드
+    nodeId,
+    nodeType,
+    journalName: toPlainText(item.plctNm || ''),
+    authors,
+    externalLink: item.externalLink === true,
+    url,
+  };
+}
+
+/** NANET 검색 결과 + PDF 파일 정보 → NormalizedItem */
+export function normalizeNanetItem(searchItem, pdfFile, query) {
+  const controlNo = String(searchItem.controlNo || '');
+  const itemNo = pdfFile ? String(pdfFile.itemNo || '') : '';
+  const docid = controlNo
+    ? `nanet-${controlNo}${(itemNo && itemNo !== '1') ? `-${itemNo}` : ''}`
+    : `nanet-unknown-${Date.now()}`;
+
+  const title = toPlainText(searchItem.title || '') || '제목없음';
+  const origExt = pdfFile?.fileName?.includes('.')
+    ? pdfFile.fileName.slice(pdfFile.fileName.lastIndexOf('.')).toLowerCase()
+    : '.pdf';
+  const year = String(searchItem.publishYear || '');
+  const fileName = year ? `(${year}) ${title}${itemNo && itemNo !== '1' ? `_${itemNo}` : ''}${origExt}`
+    : `${title}${origExt}`;
+
+  // pdfCount: 검색 결과 HTML의 downloadDoc(this, controlNo, count)에서 파싱한 PDF 파일 수
+  // count==1 → itemNo 없이 직접 다운로드 (NANET JS downloadBySingleCount 동작 일치)
+  // count>1  → fetchPDFInfoList로 itemNo 획득 후 다운로드
+  const pdfCount = Number(searchItem.pdfCount || 1);
+
+  return {
+    docid,
+    source: 'nanet',
+    query,
+    title,
+    institution: normalizeInstitution(toPlainText(searchItem.publisher || '') || '국회도서관'),
+    institutionId: '',
+    year,
+    fileName,
+    fileSize: pdfFile ? Number(pdfFile.fileSize || 0) : 0,
+    keywords: '',
+    outline: toPlainText(searchItem.abstract || searchItem.description || ''),
+    summary: toPlainText(searchItem.abstract || searchItem.description || '').slice(0, 800),
+    contentPreview: toPlainText(searchItem.abstract || searchItem.description || '').slice(0, 800),
+    // NANET 전용 (다운로드 시 필요)
+    controlNo,
+    itemNo,
+    pdfCount,
+    linkSystemId: 'NADL',
+  };
+}

package/src/agent/skills/_registry.js

@@ -0,0 +1,79 @@
+/**
+ * SkillRegistry
+ *
+ * Skill 플러그인을 로드하고 관리합니다.
+ * - skillsDir의 .js 파일을 순회하여 Skill 인스턴스를 로드
+ * - base.js, _로 시작하는 파일 제외
+ * - 로드 실패한 스킬은 건너뜸 (에러 격리)
+ */
+
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export class SkillRegistry {
+  #skills = new Map();
+
+  /**
+   * skillsDir의 .js 파일을 순회하여 Skill 인스턴스를 로드합니다.
+   *
+   * @param {string} skillsDir - 절대 경로
+   */
+  async load(skillsDir) {
+    let files;
+    try {
+      files = await readdir(skillsDir);
+    } catch {
+      // 디렉토리 없으면 graceful degradation
+      return;
+    }
+
+    const skillFiles = files.filter(
+      f => f.endsWith('.js') && !f.startsWith('_') && f !== 'base.js'
+    );
+
+    for (const file of skillFiles) {
+      try {
+        const mod = await import(pathToFileURL(join(skillsDir, file)).href);
+        const SkillClass = mod.default;
+        if (!SkillClass || !SkillClass.manifest?.id) {
+          console.warn(`[skill] ${file}: default export 없거나 manifest.id 없음`);
+          continue;
+        }
+        const instance = new SkillClass();
+        await instance.onRegister?.();
+        this.#skills.set(SkillClass.manifest.id, instance);
+      } catch (err) {
+        console.warn(`[skill] ${file} 로드 실패: ${err.message}`);
+      }
+    }
+  }
+
+  /**
+   * ID로 스킬을 조회합니다.
+   *
+   * @param {string} id
+   * @returns {Skill|undefined}
+   */
+  get(id) {
+    return this.#skills.get(id);
+  }
+
+  /**
+   * 모든 로드된 스킬을 배열로 반환합니다.
+   *
+   * @returns {Skill[]}
+   */
+  list() {
+    return [...this.#skills.values()];
+  }
+
+  /**
+   * 등록된 스킬 수를 반환합니다.
+   *
+   * @returns {number}
+   */
+  get size() {
+    return this.#skills.size;
+  }
+}

package/src/agent/skills/base.js

@@ -0,0 +1,90 @@
+/**
+ * Skill 추상 클래스
+ *
+ * 모든 수집 플러그인은 이 클래스를 상속한다.
+ * discover() / openDownloadResponse() / normalize() 세 메서드를 반드시 구현해야 한다.
+ */
+export class Skill {
+  /**
+   * 플러그인 정적 매니페스트 — 서브클래스에서 오버라이드 필수
+   * @type {{ id: string, name: string, version: string, defaultCron: string|null, rateLimit: { rps: number, burst: number }, requiredEnv: string[], capabilities: string[] }}
+   */
+  static manifest = {
+    id: 'base',
+    name: 'Base Skill',
+    version: '0.0.0',
+    defaultCron: null,
+    rateLimit: { rps: 1, burst: 1 },
+    requiredEnv: [],
+    capabilities: [],
+  };
+
+  /**
+   * 소스별 동작 메타 — 서브클래스에서 오버라이드 가능
+   */
+  get meta() {
+    return {
+      sessionTtlMs: null,
+      minRequestIntervalMs: 0,
+      earlyStopConsecutiveEmpty: 5,
+      supportsRangeRequest: false,
+    };
+  }
+
+  /**
+   * 신규 항목 발견
+   * @param {{ since: Date|null, keywords: string[], limit: number }} options
+   * @returns {Promise<object[]>} NormalizedItem 배열
+   */
+  async discover(_options) {
+    throw new Error(`${this.constructor.manifest.id}: discover() 미구현`);
+  }
+
+  /**
+   * 단일 쿼리로 실시간 검색 (UI 외부검색용)
+   * @param {string} _query
+   * @param {{ limit?: number }} [_options]
+   * @returns {Promise<object[]>} NormalizedItem 배열
+   */
+  async search(_query, _options) {
+    throw new Error(`${this.constructor.manifest.id}: search() 미구현`);
+  }
+
+  /**
+   * 다운로드 스트림 오픈
+   * @param {object} item NormalizedItem
+   * @param {object} [options]
+   * @returns {Promise<Response>}
+   */
+  async openDownloadResponse(_item, _options) {
+    throw new Error(`${this.constructor.manifest.id}: openDownloadResponse() 미구현`);
+  }
+
+  /**
+   * 원본 항목 → NormalizedItem 변환
+   * @param {object} rawItem
+   * @returns {object}
+   */
+  normalize(_rawItem) {
+    throw new Error(`${this.constructor.manifest.id}: normalize() 미구현`);
+  }
+
+  /** 쿼리 가공 — 필요 시 서브클래스에서 오버라이드 */
+  buildQuery(options) {
+    return options.query ?? '';
+  }
+
+  /** 세션 보장 — 로그인 필요 소스에서 오버라이드 */
+  async ensureSession() {}
+
+  /** 최초 등록 시 1회 호출 */
+  async onRegister() {}
+
+  /** 주기적 상태 확인 */
+  async healthCheck() {}
+
+  /** 추가 실행 조건 — false 반환 시 tick() 건너뜀 */
+  async shouldRun(_context) {
+    return true;
+  }
+}