@clazic/urban 0.2.5 → 0.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clazic/urban",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "도시계획연구 보고서 자동 수집·지식베이스 데몬",
   "type": "module",
   "engines": {
@@ -17,7 +17,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@clazic/kordoc": "^2.4.18",
+    "@clazic/kordoc": "^2.4.19",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "@rhwp/core": "^0.7.2",
     "better-sqlite3": "^12.9.0",

package/scripts/e2e-mcp.js

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+/**
+ * Phase H-7: e2e-mcp.js
+ *
+ * Urban KB MCP 도구 E2E 검증 스크립트
+ * 실제 DB와 Wiki 파일을 사용해 8개 도구를 순차 호출하고
+ * 응답 스키마를 검증한다.
+ *
+ * 사용법:
+ *   node scripts/e2e-mcp.js
+ *
+ * Exit code: 0 = 전체 PASS, 1 = 1건 이상 FAIL
+ */
+
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { existsSync, readdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+const URBAN_HOME = process.env.URBAN_HOME ?? join(homedir(), '.urban');
+const WIKI_DIR = join(URBAN_HOME, 'wiki');
+const MAIN_DB_PATH = join(URBAN_HOME, 'urban.db');
+const GRAPH_DB_PATH = join(URBAN_HOME, 'graph.db');
+
+// DB 열기
+let mainDb = null;
+let graphDb = null;
+
+try {
+  const Database = require('better-sqlite3');
+  if (existsSync(MAIN_DB_PATH)) mainDb = new Database(MAIN_DB_PATH, { readonly: true });
+  if (existsSync(GRAPH_DB_PATH)) graphDb = new Database(GRAPH_DB_PATH, { readonly: true });
+} catch (e) {
+  console.error('❌ DB 초기화 실패:', e.message);
+  process.exit(1);
+}
+
+if (!mainDb || !graphDb) {
+  console.error('❌ urban.db 또는 graph.db 없음');
+  process.exit(1);
+}
+
+// MCP 핸들러 임포트
+const {
+  handleSearch,
+  handleNeighbors,
+  handlePath,
+  handleListWiki,
+  handleReadWiki,
+  handleSearchWiki,
+  handleListReports,
+  handleReadReport,
+} = await import('../src/mcp/handlers.js');
+
+// 테스트 유틸
+let passCount = 0;
+let failCount = 0;
+
+function pass(name, detail = '') {
+  passCount++;
+  console.log(`  ✅ PASS  ${name}${detail ? ` — ${detail}` : ''}`);
+}
+
+function fail(name, reason) {
+  failCount++;
+  console.error(`  ❌ FAIL  ${name} — ${reason}`);
+}
+
+function checkShape(result, keys, name) {
+  for (const key of keys) {
+    if (!(key in result)) {
+      fail(name, `응답에 '${key}' 키 없음`);
+      return false;
+    }
+  }
+  return true;
+}
+
+// ── 동적 테스트 데이터 수집 ──────────────────────────────────────────────
+
+const sampleTopic = graphDb.prepare(
+  `SELECT id FROM graph_nodes WHERE type='topic' ORDER BY degree DESC LIMIT 1`
+).get();
+const sampleTopicId = sampleTopic?.id ?? 'topics:도시계획';
+
+const connectedReport = graphDb.prepare(
+  `SELECT source FROM graph_edges WHERE target=? AND relation='about' LIMIT 1`
+).get(sampleTopicId);
+const sampleReportId = connectedReport?.source ?? null;
+
+// md_path가 실제 존재하는 INDEXED 보고서 탐색
+let sampleHash = null;
+{
+  const rows = mainDb.prepare(
+    `SELECT hash, md_path FROM reports WHERE status='INDEXED' AND md_path IS NOT NULL LIMIT 50`
+  ).all();
+  for (const row of rows) {
+    if (existsSync(row.md_path)) {
+      sampleHash = row.hash;
+      break;
+    }
+  }
+}
+
+const wikiTopicsDir = join(WIKI_DIR, 'topics');
+let sampleWikiSlug = null;
+if (existsSync(wikiTopicsDir)) {
+  const mdFiles = readdirSync(wikiTopicsDir).filter(f => f.endsWith('.md'));
+  if (mdFiles.length > 0) sampleWikiSlug = `topics/${mdFiles[0].replace(/\.md$/, '')}`;
+}
+
+// ── 테스트 실행 ────────────────────────────────────────────────────────────
+
+console.log('\n🔍 Urban KB MCP E2E 검증\n');
+console.log(`  DB:      ${MAIN_DB_PATH}`);
+console.log(`  GraphDB: ${GRAPH_DB_PATH}`);
+console.log(`  Wiki:    ${WIKI_DIR}`);
+console.log(`  샘플 topic:  ${sampleTopicId}`);
+console.log(`  샘플 report: ${sampleHash ?? '(없음)'}`);
+console.log('');
+
+// 1. kb.search
+{
+  const r = await handleSearch({ query: '도시', limit: 5, graphDb });
+  if (checkShape(r, ['nodes', 'total'], 'kb.search')) {
+    if (!Array.isArray(r.nodes)) fail('kb.search', 'nodes가 배열이 아님');
+    else pass('kb.search', `nodes=${r.nodes.length}건`);
+  }
+}
+
+// 2. kb.neighbors
+{
+  const r = await handleNeighbors({ nodeId: sampleTopicId, depth: 1, graphDb });
+  if (checkShape(r, ['nodes', 'edges'], 'kb.neighbors')) {
+    if (!Array.isArray(r.nodes) || !Array.isArray(r.edges))
+      fail('kb.neighbors', 'nodes/edges가 배열이 아님');
+    else pass('kb.neighbors', `nodes=${r.nodes.length}, edges=${r.edges.length}`);
+  }
+}
+
+// 3. kb.path
+{
+  const from = sampleReportId ?? 'report:nonexistent';
+  const r = await handlePath({ from, to: sampleTopicId, graphDb });
+  if (checkShape(r, ['path', 'edges'], 'kb.path')) {
+    const found = r.path !== null;
+    pass('kb.path', `found=${found}, path=${r.path?.length ?? 0}단계, edges=${r.edges?.length ?? 0}`);
+  }
+}
+
+// 4. kb.list_wiki
+{
+  const r = await handleListWiki({ wikiDir: WIKI_DIR });
+  if (checkShape(r, ['pages', 'total'], 'kb.list_wiki')) {
+    if (!Array.isArray(r.pages)) fail('kb.list_wiki', 'pages가 배열이 아님');
+    else pass('kb.list_wiki', `${r.pages.length}건`);
+  }
+}
+
+// 5. kb.read_wiki
+if (sampleWikiSlug) {
+  const r = await handleReadWiki({ slug: sampleWikiSlug, wikiDir: WIKI_DIR });
+  if ('error' in r) fail('kb.read_wiki', `error=${r.error}`);
+  else if (checkShape(r, ['slug', 'content'], 'kb.read_wiki')) {
+    if (typeof r.content !== 'string') fail('kb.read_wiki', 'content가 문자열이 아님');
+    else pass('kb.read_wiki', `slug=${r.slug}, ${r.content.length}자`);
+  }
+} else {
+  fail('kb.read_wiki', 'Wiki topics 파일 없음');
+}
+
+// 6. kb.search_wiki
+{
+  const r = await handleSearchWiki({ query: '도시', limit: 5, mainDb });
+  if (checkShape(r, ['results', 'total'], 'kb.search_wiki')) {
+    if (!Array.isArray(r.results)) fail('kb.search_wiki', 'results가 배열이 아님');
+    else pass('kb.search_wiki', `${r.results.length}건`);
+  }
+}
+
+// 7. kb.list_reports
+{
+  const r = await handleListReports({ limit: 5, offset: 0, mainDb });
+  if (checkShape(r, ['items', 'total'], 'kb.list_reports')) {
+    if (!Array.isArray(r.items)) fail('kb.list_reports', 'items가 배열이 아님');
+    else pass('kb.list_reports', `${r.items.length}건 (total=${r.total})`);
+  }
+}
+
+// 8. kb.read_report
+if (sampleHash) {
+  const r = await handleReadReport({ docid: sampleHash, mainDb, wikiDir: WIKI_DIR });
+  if ('error' in r) fail('kb.read_report', `error=${r.error}`);
+  else if (checkShape(r, ['hash', 'title'], 'kb.read_report')) {
+    pass('kb.read_report', `hash=${r.hash?.slice(0,8)}, "${String(r.title).slice(0,25)}..."`);
+  }
+} else {
+  fail('kb.read_report', 'INDEXED 보고서 없음');
+}
+
+// ── 결과 요약 ─────────────────────────────────────────────────────────────
+
+console.log(`\n${'─'.repeat(50)}`);
+console.log(`결과: ${passCount}/${passCount + failCount} PASS`);
+
+if (failCount === 0) {
+  console.log('✅ 모든 MCP 도구 E2E 검증 통과\n');
+  process.exit(0);
+} else {
+  console.error(`❌ ${failCount}건 FAIL\n`);
+  process.exit(1);
+}

package/scripts/postinstall.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// postinstall: graphify 설치 → urban 자동 설정 → 데몬 등록 + 시작
+// 모든 단계는 실패해도 설치 자체를 중단하지 않음 (exit 0 보장)
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+try {
+  // ── 1. graphify 설치 (선택 기능, 실패 무시) ─────────────────────────────────
+  await import('./setup-graphify.js').catch(() => {});
+
+  // ── 2. urban 자동 설정 (기본값으로 .env 생성) ─────────────────────────────────
+  const URBAN_HOME = process.env.URBAN_HOME ?? join(homedir(), '.urban');
+  const URBAN_PORT = process.env.URBAN_PORT ?? '7777';
+
+  for (const dir of ['', 'logs', 'wiki', 'inbox', 'archive', 'backups']) {
+    mkdirSync(join(URBAN_HOME, dir), { recursive: true });
+  }
+
+  const envPath = join(URBAN_HOME, '.env');
+  if (!existsSync(envPath)) {
+    writeFileSync(envPath, [
+      `URBAN_HOME=${URBAN_HOME}`,
+      `URBAN_PORT=${URBAN_PORT}`,
+      '',
+    ].join('\n'), 'utf8');
+    console.log(`[urban] 설정 파일 생성: ${envPath}`);
+  } else {
+    console.log(`[urban] 설정 파일 이미 존재: ${envPath}`);
+  }
+
+  // ── 3. 데몬 등록 + 시작 ───────────────────────────────────────────────────────
+  try {
+    const { installDaemon, startDaemon } = await import('../src/install/daemon.js');
+    const installResult = await installDaemon();
+    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`);
+    } else {
+      console.warn(`[urban] 데몬 자동 등록 실패 — 'urban install && urban start' 로 수동 시작`);
+      console.warn(`       원인: ${installResult.message}`);
+    }
+  } catch (err) {
+    console.warn(`[urban] 데몬 자동 시작 건너뜀 — 'urban install && urban start' 로 수동 시작`);
+  }
+} catch (err) {
+  // postinstall 전체 실패해도 npm install은 성공으로 처리
+  console.warn(`[urban] postinstall 경고: ${err.message}`);
+}
+
+process.exit(0);

package/scripts/setup-graphify.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// postinstall: uv 설치 확인 → graphifyy 가상환경 구성 + 터미널용 symlink 생성
+import { execSync, spawnSync } from 'child_process';
+import { existsSync, mkdirSync, symlinkSync, unlinkSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+const isWin = process.platform === 'win32';
+const PYTHON_VERSION = '3.12';
+const uvEnvDir = join(homedir(), '.urban', '.venv');
+const pythonBin = join(uvEnvDir, isWin ? 'Scripts/python.exe' : 'bin/python');
+const graphifyBin = join(uvEnvDir, isWin ? 'Scripts/graphify.exe' : 'bin/graphify');
+const localBin = join(homedir(), '.local', 'bin');
+const symlinkTarget = join(localBin, isWin ? 'graphify.cmd' : 'graphify');
+
+function findUv() {
+  try { execSync(isWin ? 'where uv' : 'which uv', { stdio: 'ignore' }); return 'uv'; } catch {}
+  const candidates = isWin
+    ? [join(homedir(), '.local', 'bin', 'uv.exe'), join(homedir(), '.cargo', 'bin', 'uv.exe')]
+    : [join(homedir(), '.local', 'bin', 'uv'), join(homedir(), '.cargo', 'bin', 'uv')];
+  return candidates.find(p => existsSync(p)) ?? null;
+}
+
+function installUv() {
+  console.log('[urban] uv 설치 중...');
+  if (isWin) {
+    execSync('powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"', { stdio: 'inherit' });
+  } else {
+    execSync('curl -LsSf https://astral.sh/uv/install.sh | sh', { stdio: 'inherit' });
+  }
+  return findUv();
+}
+
+// uv 자체 관리 Python 경로 반환 (없으면 자동 설치)
+function ensureUvPython(uv) {
+  console.log(`[urban] uv Python ${PYTHON_VERSION} 준비 중...`);
+  spawnSync(uv, ['python', 'install', PYTHON_VERSION], { stdio: 'inherit', shell: isWin });
+  const result = spawnSync(uv, ['python', 'find', PYTHON_VERSION], { stdio: 'pipe', shell: isWin, encoding: 'utf8' });
+  const path = result.stdout?.trim();
+  if (!path) throw new Error(`uv python find ${PYTHON_VERSION} 실패`);
+  console.log(`[urban] uv Python 경로: ${path}`);
+  return path;
+}
+
+function run(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, { stdio: 'inherit', shell: isWin, ...opts });
+  if (r.status !== 0) throw new Error(`${cmd} ${args.join(' ')} 실패 (exit ${r.status})`);
+}
+
+// 터미널 어디서나 실행 가능하도록 symlink(Unix) 또는 .cmd 래퍼(Windows) 생성
+function createSymlink() {
+  mkdirSync(localBin, { recursive: true });
+
+  if (isWin) {
+    const wrapper = `@echo off\n"${graphifyBin}" %*\n`;
+    writeFileSync(symlinkTarget, wrapper);
+    console.log('[urban] graphify 래퍼 생성 →', symlinkTarget);
+  } else {
+    try { unlinkSync(symlinkTarget); } catch {}
+    symlinkSync(graphifyBin, symlinkTarget);
+    console.log('[urban] graphify symlink 생성 →', symlinkTarget);
+  }
+
+  // ~/.local/bin 이 PATH에 없으면 안내
+  const pathDirs = (process.env.PATH ?? '').split(isWin ? ';' : ':');
+  if (!pathDirs.includes(localBin)) {
+    console.warn(`[urban] ⚠️  ${localBin} 이 PATH에 없습니다.`);
+    if (isWin) {
+      console.warn(`       setx PATH "%PATH%;${localBin}"`);
+    } else {
+      const rc = process.env.SHELL?.includes('zsh') ? '~/.zshrc' : '~/.bashrc';
+      console.warn(`       ${rc} 에 추가: export PATH="$HOME/.local/bin:$PATH"`);
+    }
+  }
+}
+
+if (process.env.URBAN_SKIP_GRAPHIFY === '1') {
+  console.log('[urban] URBAN_SKIP_GRAPHIFY=1 — graphify 설치 건너뜀');
+  process.exit(0);
+}
+
+try {
+  let uv = findUv();
+  if (!uv) uv = installUv();
+  if (!uv) throw new Error('uv 설치 실패 — https://docs.astral.sh/uv/getting-started/installation 참고');
+
+  if (existsSync(pythonBin)) {
+    console.log('[urban] graphify 환경이 이미 존재합니다:', uvEnvDir);
+    createSymlink();
+    process.exit(0);
+  }
+
+  // uv 자체 관리 Python 사용 (Homebrew·시스템 Python 무시)
+  const uvPython = ensureUvPython(uv);
+
+  console.log('[urban] graphify 가상환경 생성 중...');
+  run(uv, ['venv', uvEnvDir, '--python', uvPython]);
+
+  console.log('[urban] graphifyy 설치 중...');
+  run(uv, ['pip', 'install', '--python', pythonBin, 'graphifyy']);
+
+  console.log('[urban] graphify 설치 완료 →', uvEnvDir);
+  createSymlink();
+} catch (err) {
+  console.warn('[urban] graphify 설치 실패 (선택 기능이므로 계속):', err.message);
+  process.exit(0);
+}