harulog 0.1.0

package/.env.example

@@ -0,0 +1,14 @@
+HARULOG_HOME=
+HARULOG_LAUNCH_AGENTS_DIR=
+GEMINI_API_KEY=
+GOOGLE_API_KEY=
+GEMINI_MODEL=gemini-2.5-flash
+CODEX_HOME=
+LOCAL_GIT_REPOS=
+LOCAL_GIT_SCAN_ROOTS=
+LOCAL_GIT_SCAN_DEPTH=2
+TOPIC_COUNT=5
+RECOMMENDATION_WINDOW_DAYS=14
+SCHEDULE_WEEKDAY=5
+SCHEDULE_HOUR=9
+LLM_PROVIDER=gemini

package/README.md

@@ -0,0 +1,111 @@
+# haruLog
+
+`harulog`는 Codex 대화 이력과 로컬 git 작업 흔적을 읽어서 글감과 초안을 추천하는 macOS용 CLI다. 배포 목표는 `bunx harulog ...` 한 줄로 어느 PC에서든 설정하고, `launchd`가 매주 금요일 오전 9시에 자동 실행되도록 만드는 것이다.
+
+## Quick Start
+
+```bash
+bunx harulog setup
+bunx harulog run --force --ignore-history
+```
+
+기본 설정이 끝나면 사용자 데이터는 `~/Library/Application Support/harulog` 아래에 저장된다.
+
+- `config.json`: 사용자 설정
+- `state.json`: 마지막 실행 상태
+- `topic_history.json`: 최근 추천 이력
+- `outputs/`: JSON/Markdown 결과
+- `logs/`: scheduler 로그
+- `bin/`: scheduler wrapper script
+
+## Commands
+
+```bash
+bunx harulog setup
+bunx harulog run
+bunx harulog run --force --ignore-history
+bunx harulog scheduler install
+bunx harulog scheduler status
+bunx harulog doctor
+```
+
+- `setup`: 대화형 설정 마법사. Gemini 키, Codex 경로, git scan root, 스케줄을 저장하고 필요하면 launchd를 설치한다.
+- `run`: 수동으로 1회 실행한다.
+- `run --scheduled`: launchd용 실행 모드. 이번 주 금요일 09:00 스케줄 창이 열렸을 때만 동작한다.
+- `run --force`: 스케줄 조건을 무시하고 강제로 실행한다.
+- `run --ignore-history`: 최근 추천 이력을 무시하고 테스트용으로 다시 생성한다.
+- `scheduler install`: `~/Library/LaunchAgents/com.harulog.weekly-topics.plist`와 wrapper script를 설치한다.
+- `scheduler uninstall`: launchd 등록과 wrapper script를 제거한다.
+- `scheduler status`: 설치 상태와 plist/wrapper/log 경로를 보여준다.
+- `doctor`: Bun, Gemini 키, Codex 경로, git repo 탐색, launchd 상태를 점검한다.
+
+## Scheduler
+
+자동 실행은 `launchd` LaunchAgent를 사용한다.
+
+- 스케줄: 매주 금요일 09:00
+- `RunAtLoad`: 로그인 직후 catch-up 실행
+- wrapper: `~/Library/Application Support/harulog/bin/run-weekly.sh`
+- 실제 실행 명령: 설치 시점 버전으로 고정된 `bun x --bun harulog@<version> run --scheduled`
+
+즉 scheduler는 “항상 최신”이 아니라 설치 시점 패키지 버전을 고정해서 실행한다.
+
+## Config
+
+`setup`이 만드는 기본 설정 구조는 아래와 같다.
+
+```json
+{
+  "llmProvider": "gemini",
+  "geminiModel": "gemini-2.5-flash",
+  "geminiApiKeySource": "config",
+  "codexHome": "/Users/me/.codex",
+  "localGitRepos": [],
+  "localGitScanRoots": [
+    "/Users/me/Documents/work"
+  ],
+  "localGitScanDepth": 2,
+  "schedule": {
+    "weekday": 5,
+    "hour": 9
+  },
+  "topicCount": 5,
+  "recommendationWindowDays": 14
+}
+```
+
+Gemini API 키는 기본적으로 `config.json`에 저장할 수 있고, `GEMINI_API_KEY` 또는 `GOOGLE_API_KEY` 환경변수가 있으면 그 값이 우선한다.
+
+## Development
+
+repo 안에서 개발할 때는 아래 명령을 쓴다.
+
+```bash
+bun install
+bun run dev
+bun run job:weekly
+bun run job:weekly:force
+bun run src/cli.ts help
+bun run check
+```
+
+- `job:weekly`: CLI의 `run --scheduled`와 같다.
+- `job:weekly:force`: CLI의 `run --scheduled --force`와 같다.
+- `job:daily`, `job:daily:force`: 이전 이름과의 호환 alias다.
+
+## Optional Env Overrides
+
+repo 개발이나 디버깅용으로는 [.env.example](/Users/seojeonghyeon/Documents/work/haruLog/.env.example)에 있는 환경변수 override를 사용할 수 있다.
+
+- `HARULOG_HOME`
+- `HARULOG_LAUNCH_AGENTS_DIR`
+- `GEMINI_API_KEY` / `GOOGLE_API_KEY`
+- `CODEX_HOME`
+- `LOCAL_GIT_REPOS`
+- `LOCAL_GIT_SCAN_ROOTS`
+- `LOCAL_GIT_SCAN_DEPTH`
+- `TOPIC_COUNT`
+- `RECOMMENDATION_WINDOW_DAYS`
+- `SCHEDULE_WEEKDAY`
+- `SCHEDULE_HOUR`
+- `LLM_PROVIDER`

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "harulog",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "packageManager": "bun@1.3.6",
+  "bin": {
+    "harulog": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    ".env.example"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "cli": "bun run src/cli.ts",
+    "job:weekly": "bun run src/cli.ts run --scheduled",
+    "job:weekly:force": "bun run src/cli.ts run --scheduled --force",
+    "job:daily": "bun run src/cli.ts run --scheduled",
+    "job:daily:force": "bun run src/cli.ts run --scheduled --force",
+    "check": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {}
+}

package/src/appPaths.ts

@@ -0,0 +1,67 @@
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const APP_NAME = "harulog";
+export const LAUNCH_AGENT_LABEL = "com.harulog.weekly-topics";
+
+export interface AppPaths {
+  packageRoot: string;
+  packageManifestPath: string;
+  appHome: string;
+  configPath: string;
+  statePath: string;
+  topicHistoryPath: string;
+  outputsDir: string;
+  logsDir: string;
+  binDir: string;
+  launchAgentsDir: string;
+  launchAgentPath: string;
+  launchAgentLogPath: string;
+  schedulerWrapperPath: string;
+}
+
+function resolvePackageRoot(): string {
+  const currentFile = fileURLToPath(import.meta.url);
+  return path.resolve(path.dirname(currentFile), "..");
+}
+
+export function resolveAppHome(): string {
+  const override = process.env.HARULOG_HOME?.trim();
+  if (override) {
+    return path.resolve(override);
+  }
+
+  return path.join(os.homedir(), "Library", "Application Support", APP_NAME);
+}
+
+export function resolveLaunchAgentsDir(): string {
+  const override = process.env.HARULOG_LAUNCH_AGENTS_DIR?.trim();
+  if (override) {
+    return path.resolve(override);
+  }
+
+  return path.join(os.homedir(), "Library", "LaunchAgents");
+}
+
+export function resolveAppPaths(): AppPaths {
+  const packageRoot = resolvePackageRoot();
+  const appHome = resolveAppHome();
+  const launchAgentsDir = resolveLaunchAgentsDir();
+
+  return {
+    packageRoot,
+    packageManifestPath: path.join(packageRoot, "package.json"),
+    appHome,
+    configPath: path.join(appHome, "config.json"),
+    statePath: path.join(appHome, "state.json"),
+    topicHistoryPath: path.join(appHome, "topic_history.json"),
+    outputsDir: path.join(appHome, "outputs"),
+    logsDir: path.join(appHome, "logs"),
+    binDir: path.join(appHome, "bin"),
+    launchAgentsDir,
+    launchAgentPath: path.join(launchAgentsDir, `${LAUNCH_AGENT_LABEL}.plist`),
+    launchAgentLogPath: path.join(appHome, "logs", "launchd-weekly-topics.log"),
+    schedulerWrapperPath: path.join(appHome, "bin", "run-weekly.sh")
+  };
+}

package/src/cli.ts

@@ -0,0 +1,120 @@
+#!/usr/bin/env bun
+
+import { loadConfig } from "./config";
+import { runDoctor } from "./doctor";
+import { runTopicsJob } from "./services/topicsJob";
+import { getSchedulerStatus, installScheduler, uninstallScheduler } from "./scheduler";
+import { runSetupWizard } from "./setup";
+
+function hasFlag(args: string[], flag: string): boolean {
+  return args.includes(flag);
+}
+
+function printUsage(): void {
+  console.log(`harulog
+
+Usage:
+  harulog setup [--defaults] [--install-scheduler] [--skip-scheduler] [--write-only-scheduler]
+  harulog run [--force] [--ignore-history] [--scheduled]
+  harulog scheduler install [--write-only]
+  harulog scheduler uninstall [--write-only]
+  harulog scheduler status
+  harulog doctor
+  harulog version
+`);
+}
+
+async function handleRun(args: string[]): Promise<number> {
+  const result = await runTopicsJob({
+    force: hasFlag(args, "--force"),
+    ignoreHistory: hasFlag(args, "--ignore-history"),
+    scheduled: hasFlag(args, "--scheduled")
+  });
+
+  console.log(result.reason);
+  console.log(`Suggestions: ${result.suggestions.length}`);
+  return result.skipped ? 0 : 0;
+}
+
+async function handleScheduler(args: string[]): Promise<number> {
+  const subcommand = args[0];
+  const config = await loadConfig();
+
+  if (subcommand === "install") {
+    const status = await installScheduler(config, { writeOnly: hasFlag(args, "--write-only") });
+    console.log(`Installed scheduler: ${status.plistPath}`);
+    return 0;
+  }
+
+  if (subcommand === "uninstall") {
+    await uninstallScheduler(config, { writeOnly: hasFlag(args, "--write-only") });
+    console.log(`Removed scheduler: ${config.launchAgentPath}`);
+    return 0;
+  }
+
+  if (subcommand === "status") {
+    const status = await getSchedulerStatus(config);
+    console.log(`label: ${status.label}`);
+    console.log(`installed: ${status.installed}`);
+    console.log(`loaded: ${status.loaded}`);
+    console.log(`plist: ${status.plistPath}`);
+    console.log(`wrapper: ${status.wrapperPath}`);
+    console.log(`log: ${status.logPath}`);
+    return 0;
+  }
+
+  throw new Error("scheduler requires one of: install, uninstall, status");
+}
+
+async function handleVersion(): Promise<number> {
+  const config = await loadConfig();
+  console.log(config.packageVersion);
+  return 0;
+}
+
+async function main(argv: string[]): Promise<number> {
+  const [command = "help", ...rest] = argv;
+
+  if (command === "help" || command === "--help" || command === "-h") {
+    printUsage();
+    return 0;
+  }
+
+  if (command === "version" || command === "--version" || command === "-v") {
+    return handleVersion();
+  }
+
+  if (command === "setup") {
+    await runSetupWizard({
+      defaults: hasFlag(rest, "--defaults"),
+      installScheduler: hasFlag(rest, "--install-scheduler"),
+      skipScheduler: hasFlag(rest, "--skip-scheduler"),
+      writeOnlyScheduler: hasFlag(rest, "--write-only-scheduler")
+    });
+    return 0;
+  }
+
+  if (command === "run") {
+    return handleRun(rest);
+  }
+
+  if (command === "scheduler") {
+    return handleScheduler(rest);
+  }
+
+  if (command === "doctor") {
+    return runDoctor();
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+main(process.argv.slice(2))
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((error) => {
+    console.error("[error] harulog command failed");
+    console.error(error);
+    process.exitCode = 1;
+  });

package/src/collectors/codex.ts

@@ -0,0 +1,72 @@
+import { readFile } from "node:fs/promises";
+
+import type { AppConfig } from "../config";
+import type { ActivityItem } from "../types";
+import { logWarn } from "../utils/logger";
+
+interface CodexSessionIndexRecord {
+  id: string;
+  thread_name?: string;
+  updated_at: string;
+}
+
+function sanitizeThreadName(value: string | undefined): string {
+  const raw = value?.trim();
+  if (!raw) {
+    return "Untitled Codex session";
+  }
+
+  return raw
+    .replace(/[\u0000-\u001f]+/g, " ")
+    .replace(/[\]\)\}"'`〛】]+$/g, "")
+    .replace(/\s+/g, " ")
+    .trim() || "Untitled Codex session";
+}
+
+function toTags(threadName: string): string[] {
+  return threadName
+    .toLowerCase()
+    .split(/[^a-z0-9가-힣]+/u)
+    .map((token) => token.trim())
+    .filter((token) => token.length >= 2)
+    .slice(0, 6);
+}
+
+function mapRecordToActivity(record: CodexSessionIndexRecord, config: AppConfig): ActivityItem {
+  const title = sanitizeThreadName(record.thread_name);
+
+  return {
+    id: `codex:${record.id}`,
+    source: "codex",
+    type: "session",
+    title,
+    summary: `Codex session captured from session_index.jsonl: ${title}`,
+    timestamp: record.updated_at,
+    tags: toTags(title),
+    weight: 2,
+    status: "done",
+    evidence: [config.codexSessionIndexPath],
+    metadata: {
+      threadId: record.id,
+      hasLogsIndex: true
+    }
+  };
+}
+
+export async function collectCodexActivities(config: AppConfig): Promise<ActivityItem[]> {
+  try {
+    const content = await readFile(config.codexSessionIndexPath, "utf8");
+    const items = content
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map((line) => JSON.parse(line) as CodexSessionIndexRecord)
+      .filter((record) => record.id && record.updated_at)
+      .map((record) => mapRecordToActivity(record, config));
+
+    return items;
+  } catch (error) {
+    logWarn(`Codex collector could not read ${config.codexSessionIndexPath}: ${String(error)}`);
+    return [];
+  }
+}

package/src/collectors/github.ts

@@ -0,0 +1,8 @@
+import type { AppConfig } from "../config";
+import type { ActivityItem } from "../types";
+import { logInfo } from "../utils/logger";
+
+export async function collectGitHubActivities(_config: AppConfig): Promise<ActivityItem[]> {
+  logInfo("GitHub collector is still a placeholder. Returning no activities for now.");
+  return [];
+}