harulog 0.1.0

package/src/doctor.ts

@@ -0,0 +1,63 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+import { listLocalGitRepositories } from "./collectors/localGit";
+import { loadConfig } from "./config";
+import { getSchedulerStatus } from "./scheduler";
+import { pathExists } from "./utils/file";
+
+const execFileAsync = promisify(execFile);
+
+async function hasGit(): Promise<boolean> {
+  try {
+    await execFileAsync("git", ["--version"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function runDoctor(): Promise<number> {
+  const config = await loadConfig();
+  const schedulerStatus = await getSchedulerStatus(config);
+  const [codexIndexExists, codexLogsExist, gitExists, repoPaths] = await Promise.all([
+    pathExists(config.codexSessionIndexPath),
+    pathExists(config.codexLogsPath),
+    hasGit(),
+    listLocalGitRepositories(config)
+  ]);
+
+  const checks = [
+    { label: "config file", ok: config.configExists, detail: config.configPath },
+    {
+      label: "gemini api key",
+      ok: Boolean(config.geminiApiKey),
+      detail: config.geminiApiKey ? `configured via ${config.geminiApiKeySource}` : "missing"
+    },
+    { label: "codex session index", ok: codexIndexExists, detail: config.codexSessionIndexPath },
+    { label: "codex logs sqlite", ok: codexLogsExist, detail: config.codexLogsPath },
+    { label: "git executable", ok: gitExists, detail: gitExists ? "available" : "missing" },
+    {
+      label: "local git repositories",
+      ok: repoPaths.length > 0,
+      detail: `${repoPaths.length} repositories from ${config.localGitScanRoots.join(", ")}`
+    },
+    {
+      label: "launchd scheduler",
+      ok: schedulerStatus.installed,
+      detail: schedulerStatus.installed
+        ? `${schedulerStatus.loaded ? "loaded" : "installed"} at ${schedulerStatus.plistPath}`
+        : "not installed"
+    }
+  ];
+
+  console.log(`harulog doctor (${config.packageVersion})`);
+  console.log(`app home: ${config.appHome}`);
+  console.log("");
+
+  for (const check of checks) {
+    console.log(`${check.ok ? "[ok]" : "[warn]"} ${check.label}: ${check.detail}`);
+  }
+
+  return checks.every((check) => check.ok) ? 0 : 1;
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+import { loadConfig } from "./config";
+import { formatWeekdayLabel } from "./utils/date";
+
+const config = await loadConfig();
+
+console.log("haruLog CLI package is ready.");
+console.log(`package: ${config.packageName}@${config.packageVersion}`);
+console.log(`appHome: ${config.appHome}`);
+console.log(`configPath: ${config.configPath}`);
+console.log(`codexSessionIndexPath: ${config.codexSessionIndexPath}`);
+console.log(`llmProvider: ${config.llmProvider}`);
+console.log(`geminiModel: ${config.geminiModel}`);
+console.log(
+  `schedule: every ${formatWeekdayLabel(config.scheduleWeekday)} at ${String(config.scheduleHour).padStart(2, "0")}:00`
+);
+console.log(
+  `localGitScanRoots: ${config.localGitScanRoots.length > 0 ? config.localGitScanRoots.join(", ") : "(none)"}`
+);
+console.log(
+  `localGitRepos: ${config.localGitRepos.length > 0 ? config.localGitRepos.join(", ") : "(auto-discover)"}`
+);
+console.log("Use `bun run src/cli.ts help` to inspect CLI commands.");

package/src/jobs/dailyTopics.ts

@@ -0,0 +1,10 @@
+import { runTopicsJob } from "../services/topicsJob";
+
+const force = process.argv.includes("--force");
+const ignoreHistory = process.argv.includes("--ignore-history");
+
+runTopicsJob({ force, ignoreHistory, scheduled: true }).catch((error) => {
+  console.error("[error] dailyTopics job failed");
+  console.error(error);
+  process.exitCode = 1;
+});

package/src/normalize/activity.ts

@@ -0,0 +1,43 @@
+import type { ActivityItem } from "../types";
+import { subtractDays } from "../utils/date";
+
+function isValidTimestamp(value: string): boolean {
+  return Number.isFinite(new Date(value).getTime());
+}
+
+function dedupeActivities(activities: ActivityItem[]): ActivityItem[] {
+  const seen = new Set<string>();
+  const result: ActivityItem[] = [];
+
+  for (const activity of activities) {
+    const key = `${activity.source}:${activity.id}`;
+    if (seen.has(key)) {
+      continue;
+    }
+
+    seen.add(key);
+    result.push(activity);
+  }
+
+  return result;
+}
+
+export function normalizeActivities(
+  activities: ActivityItem[],
+  now: Date,
+  windowDays: number
+): ActivityItem[] {
+  const windowStart = subtractDays(now, windowDays);
+
+  return dedupeActivities(
+    activities.filter((activity) => {
+      if (!isValidTimestamp(activity.timestamp)) {
+        return false;
+      }
+
+      return new Date(activity.timestamp).getTime() >= windowStart.getTime();
+    })
+  ).sort((left, right) => {
+    return new Date(right.timestamp).getTime() - new Date(left.timestamp).getTime();
+  });
+}

package/src/prompts/topicPrompt.ts

@@ -0,0 +1,142 @@
+import type { ActivityItem, TopicHistoryItem } from "../types";
+
+function toActivityPromptItem(activity: ActivityItem): Record<string, unknown> {
+  return {
+    id: activity.id,
+    source: activity.source,
+    type: activity.type,
+    title: activity.title,
+    summary: activity.summary,
+    timestamp: activity.timestamp,
+    status: activity.status,
+    tags: activity.tags,
+    weight: activity.weight,
+    evidence: activity.evidence,
+    metadata: activity.metadata ?? {}
+  };
+}
+
+function toHistoryPromptItem(item: TopicHistoryItem): Record<string, unknown> {
+  return {
+    title: item.title,
+    createdAt: item.createdAt,
+    relatedKeywords: item.relatedKeywords
+  };
+}
+
+const WRITING_QUALITY_GUIDE = [
+  "당신은 사내 기술 블로그와 외부 기술 미디어에 글을 써본 시니어 테크니컬 라이터다.",
+  "당신의 역할은 마케팅 카피라이터가 아니라, 실제 코드 변경과 운영 맥락을 정확하게 설명하는 기술 문서 작성자에 가깝다.",
+  "글의 목표는 활동 기록을 단순 요약하는 것이 아니라, 실제 문제 해결 경험을 읽을 만한 기술 블로그 초안으로 바꾸는 것이다.",
+  "문장은 자연스럽고 밀도 있게 쓰되, 마케팅 문구처럼 과장하지 않는다.",
+  "독자는 실무 개발자다. 추상적인 조언보다 상황, 판단, 트레이드오프, 배운 점이 드러나야 한다.",
+  "사실이 부족하면 보수적으로 표현하고, 입력에 없는 파일명, 수치, 원인, 결과를 만들어내지 않는다.",
+  "변경 요약은 가능한 한 실제 작업 단위, 관련 파일, 영향 범위, 동작 차이에 기대어 작성한다.",
+  "audience는 개발자, 운영자, 통합 담당자 중 누구에게 특히 유용한지 드러나게 구체화한다.",
+  "입력 근거에 환경 설정, 브랜치, 파일, API, 배포 흐름이 보이면 초안에 prerequisites, caveats, troubleshooting 포인트를 자연스럽게 녹여라.",
+  "마이그레이션, 롤백, 설정 변경, 운영상 주의가 중요한 주제라면 그 포인트를 빼먹지 않는다.",
+  "제목은 블로그 게시물 제목처럼 구체적이고 읽고 싶게 써야 한다. '정리할 만한', '포인트', '이 글에서는' 같은 뻔한 표현은 피한다.",
+  "reason는 한두 문장이 아니라, 왜 이 주제가 지금 가치 있는지 편집자의 시선으로 설득력 있게 설명한다.",
+  "audience는 막연한 '개발자' 대신 어떤 상황의 개발자에게 유용한지 구체화한다.",
+  "outline은 목차처럼 보이되, 실제 글 전개가 느껴지는 짧은 문장 4개로 작성한다.",
+  "draft는 기술 블로그 초안답게 서론-문제 상황-탐색/판단-해결/교훈 흐름이 살아 있어야 한다.",
+  "draft는 최소 4문단, 권장 5~7문단으로 작성하고, 문단마다 역할이 다르게 느껴져야 한다.",
+  "draft 첫 문단은 독자의 관심을 끌 수 있도록 실제 상황이나 문제의식으로 시작한다. 상투적인 인삿말로 시작하지 않는다.",
+  "draft에는 왜 이 문제가 헷갈렸는지, 어떤 기준으로 접근을 바꿨는지, 해결 과정에서 무엇이 핵심이었는지가 드러나야 한다.",
+  "draft 마지막 문단은 단순 요약 대신, 실무적인 교훈이나 재사용 가능한 판단 기준으로 마무리한다.",
+  "draft는 글쓰기 과정 자체를 설명하지 않는다. '이 초안은', '이 글감은', '활동 기록을 글감으로 전환', '무엇을 문제로 볼지부터 판단해야 한다' 같은 메타 서술은 금지한다.",
+  "실제 변경이 무엇인지 설명하지 못한 채 추상적인 생산성 이야기로 흐르지 않는다.",
+  "반복적으로 같은 표현을 복사하듯 쓰지 않는다. 특히 '단순한 기능 추가보다', '이 글에서는', '어디에서 막혔는지와 무엇을 확인했는지' 같은 템플릿 문장을 그대로 쓰지 않는다."
+];
+
+const TECHNICAL_WRITING_MODE = [
+  "1. 활동 데이터에서 실제 변경 내용, 영향을 받는 대상, 운영 맥락을 먼저 파악한다.",
+  "2. 글의 전개는 가능한 한 adopt, configure, migrate, troubleshoot 같은 실무 과업 관점으로 구조화한다.",
+  "3. 초안에는 caveat, prerequisite, limit, tradeoff를 독자가 바로 써먹을 수 있게 녹여 쓴다.",
+  "4. 파일명, 브랜치, 커밋, 작업 흐름에 대한 서술은 입력 evidence와 metadata에 맞아야 한다."
+];
+
+const SUGGESTION_RULES = [
+  "가능하면 하나의 suggestion에 서로 관련 있는 evidenceIds를 2~3개까지 묶어 더 풍부한 맥락을 만들어라.",
+  "다만 evidenceIds는 반드시 입력 activities에 실제로 존재하는 id만 사용해야 한다.",
+  "activities의 제목만 보고도 충분히 추론 가능한 범위에서만 맥락을 확장하라.",
+  "단순 push 이벤트만으로 맥락이 빈약하면, 관련 commit이나 같은 주제의 activity를 함께 evidenceIds에 묶어 해상도를 높여라.",
+  "git 활동에 metadata.changedFiles, repoName, branchName, relatedCommitTitle이 있다면 글의 맥락을 더 구체화하는 단서로 활용하라.",
+  "파일명은 강한 힌트지만 구현 세부사항의 확정 근거는 아니다. 파일명만으로 내부 로직을 단정하지 않는다.",
+  "근거가 부족한 주제는 억지로 장식하지 말고, 더 해상도가 높은 활동을 우선 추천하라.",
+  "최근 추천 이력과 제목이나 핵심 키워드가 크게 겹치는 주제는 피하라."
+];
+
+const DRAFT_STRUCTURE_GUIDE = [
+  "1. 도입: 실제 문제 상황, 변경 배경, 독자가 공감할 만한 혼란 지점을 연다.",
+  "2. 맥락: 어떤 기능, 설정, 흐름, 파일, 브랜치, 작업 단위가 관련되는지 설명한다.",
+  "3. 판단: 여러 접근 중 무엇을 기준으로 선택했는지와 트레이드오프를 드러낸다.",
+  "4. 구현: 바뀐 동작이나 구조를 구체적으로 설명하되, evidence에 없는 세부사항은 단정하지 않는다.",
+  "5. 운영 포인트: 필요하면 prerequisites, 주의사항, migration/rollback, troubleshooting 힌트를 녹여 쓴다.",
+  "6. 마무리: 비슷한 상황에서 재사용 가능한 판단 기준이나 체크포인트로 끝낸다."
+];
+
+const BANNED_PATTERNS = [
+  "1. 글쓰기 과정 자체를 설명하는 메타 문장",
+  "2. 입력 evidence에 없는 구현 세부사항을 사실처럼 단정하는 문장",
+  "3. 제목만 바꿔 반복한 템플릿 초안",
+  "4. 실제 변경 내용 없이 추상적인 성장담이나 생산성 담론으로만 채운 서술"
+];
+
+export function buildTopicRecommendationPrompt(input: {
+  activities: ActivityItem[];
+  history: TopicHistoryItem[];
+  count: number;
+  now: Date;
+}): string {
+  const activities = input.activities.slice(0, 40).map(toActivityPromptItem);
+  const history = input.history.slice(-20).map(toHistoryPromptItem);
+
+  return [
+    "당신은 한국어로 글감을 추천하고 초안을 작성하는 숙련된 개발자 편집자다.",
+    "입력으로 들어온 활동 데이터만 근거로 사용해야 한다.",
+    "사실이 부족한 내용은 추측하지 말고 보수적으로 작성한다.",
+    "최근 추천 이력과 과하게 겹치는 주제는 피한다.",
+    "각 suggestion의 evidenceIds는 반드시 activities에 있는 id를 그대로 사용한다.",
+    "출력은 JSON 스키마를 정확히 따라야 하며, 모든 자연어 필드는 한국어로 작성한다.",
+    "draft는 기술 블로그 초안으로, 자연스럽고 완성도 높은 한국어 문단으로 작성한다.",
+    "outline은 글의 흐름이 드러나는 짧은 문장 4개로 작성한다.",
+    `현재 시각: ${input.now.toISOString()}`,
+    `반환할 추천 개수: ${input.count}`,
+    "",
+    "작업 방식:",
+    ...TECHNICAL_WRITING_MODE,
+    "",
+    "글쓰기 품질 가이드:",
+    ...WRITING_QUALITY_GUIDE.map((item, index) => `${index + 1}. ${item}`),
+    "",
+    "추천 생성 규칙:",
+    ...SUGGESTION_RULES.map((item, index) => `${index + 1}. ${item}`),
+    "",
+    "draft 구조 가이드:",
+    ...DRAFT_STRUCTURE_GUIDE,
+    "",
+    "금지 패턴:",
+    ...BANNED_PATTERNS,
+    "",
+    "최근 추천 이력(JSON):",
+    JSON.stringify(history, null, 2),
+    "",
+    "최근 활동 데이터(JSON):",
+    JSON.stringify(activities, null, 2),
+    "",
+    "좋은 추천의 기준:",
+    "1. 실제로 겪은 문제, 변경 흐름, 영향 범위가 보일 것",
+    "2. 다른 개발자나 운영자가 바로 써먹을 만한 판단 기준이 있을 것",
+    "3. 단순 작업 보고가 아니라 구현/운영 인사이트로 확장될 수 있을 것",
+    "4. 최근 추천 이력과 제목/키워드가 과하게 겹치지 않을 것",
+    "",
+    "draft 작성 체크리스트:",
+    "1. 첫 문단에서 문제의식이나 맥락을 실제 작업 기준으로 열 것",
+    "2. 중간 문단에서 무엇이 바뀌었고 왜 어려웠는지 설명할 것",
+    "3. 해결 또는 개선 방향을 실무적으로 풀어낼 것",
+    "4. 필요하면 caveat, prerequisite, troubleshooting을 포함할 것",
+    "5. 마지막 문단에서 재사용 가능한 교훈을 남길 것",
+    "6. 문단마다 역할이 다르고, 실제 기술 블로그처럼 읽히게 쓸 것"
+  ].join("\n");
+}

package/src/recommend/topics.ts

@@ -0,0 +1,404 @@
+import type { AppConfig } from "../config";
+import { buildTopicRecommendationPrompt } from "../prompts/topicPrompt";
+import type {
+  ActivityItem,
+  RecommendInput,
+  TopicRecommender,
+  TopicSuggestion
+} from "../types";
+import { logWarn } from "../utils/logger";
+
+const STOPWORDS = new Set([
+  "the",
+  "and",
+  "for",
+  "with",
+  "from",
+  "that",
+  "this",
+  "into",
+  "then",
+  "when",
+  "where",
+  "while",
+  "using",
+  "하면서",
+  "수정",
+  "추가",
+  "작업",
+  "문제",
+  "해결",
+  "session",
+  "codex"
+]);
+
+const GEMINI_RESPONSE_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    suggestions: {
+      type: "array",
+      items: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          title: { type: "string" },
+          reason: { type: "string" },
+          audience: { type: "string" },
+          outline: {
+            type: "array",
+            items: { type: "string" }
+          },
+          draft: { type: "string" },
+          keywords: {
+            type: "array",
+            items: { type: "string" }
+          },
+          evidenceIds: {
+            type: "array",
+            items: { type: "string" }
+          },
+          score: { type: "integer" }
+        },
+        required: [
+          "title",
+          "reason",
+          "audience",
+          "outline",
+          "draft",
+          "keywords",
+          "evidenceIds",
+          "score"
+        ]
+      }
+    }
+  },
+  required: ["suggestions"]
+} as const;
+
+interface RecommendationPayload {
+  suggestions?: unknown;
+}
+
+interface SuggestionPayload {
+  title?: unknown;
+  reason?: unknown;
+  audience?: unknown;
+  outline?: unknown;
+  draft?: unknown;
+  keywords?: unknown;
+  evidenceIds?: unknown;
+  score?: unknown;
+}
+
+interface GeminiErrorPayload {
+  error?: {
+    code?: number;
+    message?: string;
+    status?: string;
+  };
+}
+
+interface GeminiGenerateContentResponse {
+  candidates?: Array<{
+    content?: {
+      parts?: Array<{
+        text?: string;
+      }>;
+    };
+  }>;
+}
+
+function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .split(/[^a-z0-9가-힣]+/u)
+    .map((token) => token.trim())
+    .filter((token) => token.length >= 2 && !STOPWORDS.has(token));
+}
+
+function overlapCount(left: string[], right: string[]): number {
+  const rightSet = new Set(right);
+  return left.filter((item) => rightSet.has(item)).length;
+}
+
+function uniqueStrings(values: string[], limit: number): string[] {
+  const result: string[] = [];
+  const seen = new Set<string>();
+
+  for (const value of values) {
+    const normalized = value.trim().toLowerCase();
+    if (!normalized || seen.has(normalized)) {
+      continue;
+    }
+
+    seen.add(normalized);
+    result.push(value.trim());
+
+    if (result.length >= limit) {
+      break;
+    }
+  }
+
+  return result;
+}
+
+function shouldSkipByHistory(
+  title: string,
+  historyTitles: Set<string>,
+  historyKeywords: string[][]
+): boolean {
+  const normalizedTitle = title.trim().toLowerCase();
+  if (historyTitles.has(normalizedTitle)) {
+    return true;
+  }
+
+  const keywords = tokenize(title);
+  return historyKeywords.some((saved) => overlapCount(keywords, saved) >= 2);
+}
+
+function clampScore(value: unknown, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return fallback;
+  }
+
+  return Math.max(1, Math.min(100, Math.round(value)));
+}
+
+function toStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value
+    .filter((item): item is string => typeof item === "string")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function buildPlaceholderDraft(activity: ActivityItem): string {
+  return [
+    `${activity.title} 같은 작업은 결과만 보면 한 줄로 설명되지만, 실제 구현 과정에서는 맥락을 정리하는 방식에 따라 난이도가 크게 달라진다. 특히 최근 활동 기록을 글감으로 전환하려면 무엇을 문제로 볼지, 어디까지를 경험으로 묶을지부터 판단해야 한다.`,
+    `이 초안은 그런 판단의 흐름을 중심에 둔다. 단순히 무엇을 만들었는지 나열하기보다, 왜 이 주제가 기술 블로그 글감이 되는지, 구현 과정에서 어떤 관점이 중요했는지, 그리고 어떤 지점이 다른 개발자에게도 전달 가치가 있는지를 풀어내는 방향이다.`,
+    `본문에서는 먼저 작업의 배경과 문제의식을 설명하고, 이어서 탐색 과정에서 드러난 고민과 선택 기준을 정리할 수 있다. 마지막에는 이번 경험이 이후 비슷한 구현이나 리팩터링 상황에서 어떤 기준으로 재사용될 수 있는지까지 연결하면 글의 완성도가 높아진다.`
+  ].join("\n\n");
+}
+
+function buildFallbackSuggestion(activity: ActivityItem): TopicSuggestion {
+  const keywords = uniqueStrings(tokenize(`${activity.title} ${activity.summary}`), 5);
+  const title = `${activity.title}를 통해 본 구현 판단과 설계 포인트`;
+
+  return {
+    title,
+    reason: `${activity.source} 기록에 실제 작업 흔적이 남아 있고, 제목만으로도 문제의식과 구현 맥락이 비교적 선명하게 드러난다. 기술 블로그 주제로 확장했을 때 실무적인 판단 과정을 담기 좋다.`,
+    audience: "비슷한 구현 흐름이나 설계 선택을 고민하는 실무 개발자",
+    outline: [
+      `${activity.title}를 다루게 된 배경과 문제의식`,
+      "구현 과정에서 헷갈렸던 지점과 판단 기준",
+      "선택한 접근 방식과 그 이유",
+      "비슷한 상황에서 재사용할 수 있는 체크포인트"
+    ],
+    draft: buildPlaceholderDraft(activity),
+    keywords,
+    evidenceIds: [activity.id],
+    score: 70 + Math.min(keywords.length, 3) * 5
+  };
+}
+
+function sanitizeSuggestion(
+  payload: SuggestionPayload,
+  availableActivityIds: Set<string>
+): TopicSuggestion | null {
+  if (typeof payload.title !== "string" || typeof payload.reason !== "string") {
+    return null;
+  }
+
+  const title = payload.title.trim();
+  const reason = payload.reason.trim();
+  const audience =
+    typeof payload.audience === "string" && payload.audience.trim()
+      ? payload.audience.trim()
+      : "비슷한 문제를 겪는 개발자";
+  const outline = uniqueStrings(toStringArray(payload.outline), 4);
+  const draft =
+    typeof payload.draft === "string" && payload.draft.trim()
+      ? payload.draft.trim()
+      : "";
+  const keywords = uniqueStrings(toStringArray(payload.keywords), 5);
+  const evidenceIds = uniqueStrings(
+    toStringArray(payload.evidenceIds).filter((item) => availableActivityIds.has(item)),
+    3
+  );
+
+  if (!title || !reason || !draft || evidenceIds.length === 0) {
+    return null;
+  }
+
+  return {
+    title,
+    reason,
+    audience,
+    outline:
+      outline.length > 0
+        ? outline
+        : [
+            "이 주제를 다루게 된 배경",
+            "구현 중 실제로 겪은 문제",
+            "해결 과정에서의 핵심 판단",
+            "같은 문제를 다시 만났을 때의 체크포인트"
+          ],
+    draft,
+    keywords: keywords.length > 0 ? keywords : uniqueStrings(tokenize(title), 5),
+    evidenceIds,
+    score: clampScore(payload.score, 75)
+  };
+}
+
+export class DeterministicTopicRecommender implements TopicRecommender {
+  async recommend(input: RecommendInput): Promise<TopicSuggestion[]> {
+    const historyTitles = new Set(input.history.map((item) => item.title.trim().toLowerCase()));
+    const historyKeywords = input.history.map((item) =>
+      item.relatedKeywords.map((keyword) => keyword.toLowerCase())
+    );
+
+    const suggestions = input.activities
+      .filter((activity) => !shouldSkipByHistory(activity.title, historyTitles, historyKeywords))
+      .map((activity) => buildFallbackSuggestion(activity))
+      .sort((left, right) => right.score - left.score)
+      .slice(0, input.count);
+
+    if (suggestions.length === 0 && input.activities.length > 0) {
+      logWarn("Placeholder recommender returned no suggestions because recent topic history filtered them out.");
+    }
+
+    return suggestions;
+  }
+}
+
+export class GeminiTopicRecommender implements TopicRecommender {
+  constructor(private readonly config: AppConfig) {
+    if (!config.geminiApiKey) {
+      throw new Error(
+        "GEMINI_API_KEY or GOOGLE_API_KEY is required when LLM_PROVIDER=gemini."
+      );
+    }
+  }
+
+  async recommend(input: RecommendInput): Promise<TopicSuggestion[]> {
+    if (input.activities.length === 0) {
+      return [];
+    }
+
+    const apiKey = this.config.geminiApiKey;
+    if (!apiKey) {
+      throw new Error("GEMINI_API_KEY or GOOGLE_API_KEY is required when LLM_PROVIDER=gemini.");
+    }
+
+    const historyTitles = new Set(input.history.map((item) => item.title.trim().toLowerCase()));
+    const historyKeywords = input.history.map((item) =>
+      item.relatedKeywords.map((keyword) => keyword.toLowerCase())
+    );
+    const prompt = buildTopicRecommendationPrompt(input);
+    const availableActivityIds = new Set(input.activities.map((activity) => activity.id));
+
+    const response = await fetch(
+      `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(
+        this.config.geminiModel
+      )}:generateContent`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-goog-api-key": apiKey
+        },
+        body: JSON.stringify({
+          contents: [
+            {
+              role: "user",
+              parts: [{ text: prompt }]
+            }
+          ],
+          generationConfig: {
+            responseMimeType: "application/json",
+            responseJsonSchema: GEMINI_RESPONSE_SCHEMA
+          }
+        })
+      }
+    );
+
+    if (!response.ok) {
+      let errorMessage = `Gemini API request failed with status ${response.status}.`;
+      try {
+        const payload = (await response.json()) as GeminiErrorPayload;
+        const details = payload.error?.message?.trim();
+        if (details) {
+          errorMessage = `Gemini API request failed with status ${response.status}: ${details}`;
+        }
+      } catch {
+        const details = await response.text();
+        if (details.trim()) {
+          errorMessage = `Gemini API request failed with status ${response.status}: ${details.trim()}`;
+        }
+      }
+
+      throw new Error(errorMessage);
+    }
+
+    const payload = (await response.json()) as GeminiGenerateContentResponse;
+    const outputText = payload.candidates
+      ?.flatMap((candidate) => candidate.content?.parts ?? [])
+      .map((part) => part.text ?? "")
+      .join("")
+      .trim();
+
+    if (!outputText) {
+      throw new Error("Gemini returned an empty response.");
+    }
+
+    let parsed: RecommendationPayload;
+    try {
+      parsed = JSON.parse(outputText) as RecommendationPayload;
+    } catch (error) {
+      throw new Error(`Gemini returned invalid JSON: ${String(error)}`);
+    }
+
+    if (!Array.isArray(parsed.suggestions)) {
+      throw new Error("Gemini response did not contain a suggestions array.");
+    }
+
+    const sanitizedSuggestions = parsed.suggestions
+      .map((item) => sanitizeSuggestion(item as SuggestionPayload, availableActivityIds))
+      .filter((item): item is TopicSuggestion => item !== null);
+
+    const suggestions = sanitizedSuggestions
+      .filter((item) => !shouldSkipByHistory(item.title, historyTitles, historyKeywords))
+      .filter((item, index, array) => {
+        return (
+          array.findIndex(
+            (candidate) => candidate.title.trim().toLowerCase() === item.title.trim().toLowerCase()
+          ) === index
+        );
+      })
+      .slice(0, input.count);
+
+    if (suggestions.length === 0) {
+      if (sanitizedSuggestions.length === 0) {
+        logWarn("Gemini returned no usable suggestions after validation.");
+      } else {
+        logWarn(
+          `Gemini returned ${sanitizedSuggestions.length} validated suggestions, but all were filtered out by recent topic history.`
+        );
+      }
+    }
+
+    return suggestions;
+  }
+}
+
+export function createTopicRecommender(config: AppConfig): TopicRecommender {
+  if (config.llmProvider === "placeholder") {
+    return new DeterministicTopicRecommender();
+  }
+
+  return new GeminiTopicRecommender(config);
+}