harulog 0.1.0

package/src/scheduler.ts

@@ -0,0 +1,153 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+import type { AppConfig } from "./config";
+import { ensureDir, pathExists, removeFileIfExists, writeExecutableFile, writeTextFile } from "./utils/file";
+
+const execFileAsync = promisify(execFile);
+
+export interface SchedulerStatus {
+  installed: boolean;
+  loaded: boolean;
+  plistPath: string;
+  wrapperPath: string;
+  logPath: string;
+  label: string;
+}
+
+interface SchedulerInstallOptions {
+  writeOnly?: boolean;
+}
+
+function buildWrapperScript(config: AppConfig): string {
+  return [
+    "#!/bin/zsh",
+    "",
+    "set -euo pipefail",
+    "",
+    `export HARULOG_HOME="${config.appHome}"`,
+    `BUN_PATH="${process.execPath}"`,
+    `PACKAGE_SPEC="${config.packageName}@${config.packageVersion}"`,
+    "",
+    'if [[ ! -x "$BUN_PATH" ]]; then',
+    '  BUN_PATH="$(command -v bun || true)"',
+    "fi",
+    "",
+    'if [[ -z "$BUN_PATH" ]]; then',
+    '  echo "bun executable not found" >&2',
+    "  exit 1",
+    "fi",
+    "",
+    'exec "$BUN_PATH" x --bun "$PACKAGE_SPEC" run --scheduled'
+  ].join("\n");
+}
+
+function buildLaunchAgentPlist(config: AppConfig): string {
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    "  <dict>",
+    "    <key>Label</key>",
+    `    <string>${config.launchAgentLabel}</string>`,
+    "    <key>ProgramArguments</key>",
+    "    <array>",
+    `      <string>${config.schedulerWrapperPath}</string>`,
+    "    </array>",
+    "    <key>WorkingDirectory</key>",
+    `    <string>${config.appHome}</string>`,
+    "    <key>RunAtLoad</key>",
+    "    <true/>",
+    "    <key>StartCalendarInterval</key>",
+    "    <dict>",
+    "      <key>Weekday</key>",
+    `      <integer>${config.scheduleWeekday}</integer>`,
+    "      <key>Hour</key>",
+    `      <integer>${config.scheduleHour}</integer>`,
+    "      <key>Minute</key>",
+    "      <integer>0</integer>",
+    "    </dict>",
+    "    <key>StandardOutPath</key>",
+    `    <string>${config.launchAgentLogPath}</string>`,
+    "    <key>StandardErrorPath</key>",
+    `    <string>${config.launchAgentLogPath}</string>`,
+    "  </dict>",
+    "</plist>",
+    ""
+  ].join("\n");
+}
+
+function getLaunchCtlDomain(config: AppConfig): string {
+  if (typeof process.getuid !== "function") {
+    throw new Error(`launchctl integration requires a POSIX user id for ${config.launchAgentLabel}.`);
+  }
+
+  return `gui/${process.getuid()}`;
+}
+
+async function isLaunchAgentLoaded(config: AppConfig): Promise<boolean> {
+  if (process.platform !== "darwin") {
+    return false;
+  }
+
+  try {
+    await execFileAsync("launchctl", ["print", `${getLaunchCtlDomain(config)}/${config.launchAgentLabel}`]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function getSchedulerStatus(config: AppConfig): Promise<SchedulerStatus> {
+  return {
+    installed: await pathExists(config.launchAgentPath),
+    loaded: await isLaunchAgentLoaded(config),
+    plistPath: config.launchAgentPath,
+    wrapperPath: config.schedulerWrapperPath,
+    logPath: config.launchAgentLogPath,
+    label: config.launchAgentLabel
+  };
+}
+
+export async function installScheduler(
+  config: AppConfig,
+  options: SchedulerInstallOptions = {}
+): Promise<SchedulerStatus> {
+  await ensureDir(config.binDir);
+  await ensureDir(config.logsDir);
+  await ensureDir(config.launchAgentsDir);
+
+  await writeExecutableFile(config.schedulerWrapperPath, buildWrapperScript(config));
+  await writeTextFile(config.launchAgentPath, buildLaunchAgentPlist(config));
+
+  if (!options.writeOnly && process.platform === "darwin") {
+    const launchCtlDomain = getLaunchCtlDomain(config);
+    try {
+      await execFileAsync("launchctl", ["bootout", launchCtlDomain, config.launchAgentPath]);
+    } catch {
+      // best effort
+    }
+
+    await execFileAsync("launchctl", ["bootstrap", launchCtlDomain, config.launchAgentPath]);
+    await execFileAsync("launchctl", ["enable", `${launchCtlDomain}/${config.launchAgentLabel}`]);
+  }
+
+  return getSchedulerStatus(config);
+}
+
+export async function uninstallScheduler(
+  config: AppConfig,
+  options: SchedulerInstallOptions = {}
+): Promise<void> {
+  if (!options.writeOnly && process.platform === "darwin") {
+    const launchCtlDomain = getLaunchCtlDomain(config);
+    try {
+      await execFileAsync("launchctl", ["bootout", launchCtlDomain, config.launchAgentPath]);
+    } catch {
+      // best effort
+    }
+  }
+
+  await removeFileIfExists(config.launchAgentPath);
+  await removeFileIfExists(config.schedulerWrapperPath);
+}

package/src/services/topicsJob.ts

@@ -0,0 +1,134 @@
+import path from "node:path";
+
+import { collectCodexActivities } from "../collectors/codex";
+import { collectLocalGitActivities } from "../collectors/localGit";
+import { loadConfig, type AppConfig } from "../config";
+import { normalizeActivities } from "../normalize/activity";
+import { createTopicRecommender } from "../recommend/topics";
+import { loadTopicHistory, mergeTopicHistory, saveTopicHistory } from "../storage/history";
+import { loadRuntimeState, saveRuntimeState, shouldRunScheduledJob } from "../storage/state";
+import type { DailyJobResult } from "../types";
+import { formatLocalDateKey } from "../utils/date";
+import { ensureDir, writeJsonFile, writeTextFile } from "../utils/file";
+import { logInfo } from "../utils/logger";
+import { renderTopicsMarkdown } from "../utils/markdown";
+
+export interface RunTopicsJobOptions {
+  force?: boolean;
+  ignoreHistory?: boolean;
+  scheduled?: boolean;
+  now?: Date;
+  config?: AppConfig;
+}
+
+function buildOutputPaths(outputsDir: string, now: Date): { jsonPath: string; markdownPath: string } {
+  const dateKey = formatLocalDateKey(now);
+  return {
+    jsonPath: path.join(outputsDir, `${dateKey}-topics.json`),
+    markdownPath: path.join(outputsDir, `${dateKey}-topics.md`)
+  };
+}
+
+export async function runTopicsJob(options: RunTopicsJobOptions = {}): Promise<DailyJobResult> {
+  const config = options.config ?? (await loadConfig());
+  const now = options.now ?? new Date();
+  const force = options.force === true;
+  const ignoreHistory = options.ignoreHistory === true;
+  const scheduled = options.scheduled === true;
+
+  await ensureDir(config.appHome);
+  await ensureDir(config.outputsDir);
+  await ensureDir(config.logsDir);
+  await ensureDir(config.binDir);
+
+  let decision = {
+    shouldRun: true,
+    reason: force ? "Forced manual execution requested." : "Manual run requested."
+  };
+
+  if (scheduled) {
+    const state = await loadRuntimeState(config.statePath);
+    decision = shouldRunScheduledJob(
+      now,
+      config.scheduleWeekday,
+      config.scheduleHour,
+      state,
+      force
+    );
+  }
+
+  if (!decision.shouldRun) {
+    logInfo(decision.reason);
+    return {
+      skipped: true,
+      reason: decision.reason,
+      suggestions: []
+    };
+  }
+
+  logInfo(decision.reason);
+
+  const [codexActivities, gitActivities] = await Promise.all([
+    collectCodexActivities(config),
+    collectLocalGitActivities(config, now)
+  ]);
+
+  const activities = normalizeActivities(
+    [...codexActivities, ...gitActivities],
+    now,
+    config.recommendationWindowDays
+  );
+
+  if (ignoreHistory) {
+    logInfo("Ignoring topic history for this run.");
+  }
+
+  const history = ignoreHistory ? [] : await loadTopicHistory(config.topicHistoryPath);
+  const recommender = createTopicRecommender(config);
+  const suggestions = await recommender.recommend({
+    activities,
+    history,
+    count: config.topicCount,
+    now
+  });
+
+  const outputPaths = buildOutputPaths(config.outputsDir, now);
+  const outputPayload = {
+    generatedAt: now.toISOString(),
+    llmProvider: config.llmProvider,
+    model: config.llmProvider === "gemini" ? config.geminiModel : "placeholder",
+    activitiesConsidered: activities.length,
+    suggestions
+  };
+
+  await writeJsonFile(outputPaths.jsonPath, outputPayload);
+  await writeTextFile(
+    outputPaths.markdownPath,
+    renderTopicsMarkdown({
+      generatedAt: now.toISOString(),
+      llmProvider: config.llmProvider,
+      model: config.llmProvider === "gemini" ? config.geminiModel : "placeholder",
+      activities,
+      suggestions
+    })
+  );
+
+  if (!ignoreHistory) {
+    const nextHistory = mergeTopicHistory(history, suggestions, now);
+    await saveTopicHistory(config.topicHistoryPath, nextHistory);
+  }
+
+  await saveRuntimeState(config.statePath, {
+    lastRunAt: now.toISOString(),
+    lastOutputJsonPath: outputPaths.jsonPath,
+    lastOutputMarkdownPath: outputPaths.markdownPath
+  });
+
+  logInfo(`Saved ${suggestions.length} suggestions to ${outputPaths.jsonPath}`);
+
+  return {
+    skipped: false,
+    reason: decision.reason,
+    suggestions
+  };
+}

package/src/setup.ts

@@ -0,0 +1,147 @@
+import os from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+import { loadConfig, loadUserConfig, saveUserConfig, type UserConfig } from "./config";
+import { installScheduler } from "./scheduler";
+import { ensureDir } from "./utils/file";
+
+export interface SetupOptions {
+  defaults?: boolean;
+  installScheduler?: boolean;
+  skipScheduler?: boolean;
+  writeOnlyScheduler?: boolean;
+}
+
+function splitCsv(value: string): string[] {
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+async function askText(
+  rl: ReturnType<typeof createInterface>,
+  label: string,
+  defaultValue: string
+): Promise<string> {
+  const answer = (await rl.question(`${label}${defaultValue ? ` [${defaultValue}]` : ""}: `)).trim();
+  return answer || defaultValue;
+}
+
+async function askYesNo(
+  rl: ReturnType<typeof createInterface>,
+  label: string,
+  defaultValue: boolean
+): Promise<boolean> {
+  const suffix = defaultValue ? "Y/n" : "y/N";
+  const answer = (await rl.question(`${label} [${suffix}]: `)).trim().toLowerCase();
+  if (!answer) {
+    return defaultValue;
+  }
+
+  return answer === "y" || answer === "yes";
+}
+
+export async function runSetupWizard(options: SetupOptions = {}): Promise<void> {
+  const current = await loadUserConfig();
+  const defaults = await loadConfig();
+  const defaultCodexHome = current.codexHome || path.join(os.homedir(), ".codex");
+  const defaultRepos = (current.localGitRepos ?? []).join(", ");
+  const defaultScanRoots =
+    current.localGitScanRoots && current.localGitScanRoots.length > 0
+      ? current.localGitScanRoots.join(", ")
+      : defaults.localGitScanRoots.join(", ");
+  const defaultScanDepth = String(current.localGitScanDepth ?? defaults.localGitScanDepth);
+  const defaultWeekday = String(current.schedule?.weekday ?? defaults.scheduleWeekday);
+  const defaultHour = String(current.schedule?.hour ?? defaults.scheduleHour);
+  const defaultTopicCount = String(current.topicCount ?? defaults.topicCount);
+  const defaultWindowDays = String(
+    current.recommendationWindowDays ?? defaults.recommendationWindowDays
+  );
+  let shouldInstallScheduler = options.installScheduler === true;
+  if (options.skipScheduler === true) {
+    shouldInstallScheduler = false;
+  }
+
+  const nextConfig: UserConfig = {
+    llmProvider: "gemini",
+    geminiModel: current.geminiModel ?? defaults.geminiModel,
+    geminiApiKey: current.geminiApiKey,
+    geminiApiKeySource: current.geminiApiKey ? current.geminiApiKeySource ?? "config" : "env",
+    codexHome: defaultCodexHome,
+    localGitRepos: splitCsv(defaultRepos),
+    localGitScanRoots: splitCsv(defaultScanRoots),
+    localGitScanDepth: Number.parseInt(defaultScanDepth, 10),
+    schedule: {
+      weekday: Number.parseInt(defaultWeekday, 10),
+      hour: Number.parseInt(defaultHour, 10)
+    },
+    topicCount: Number.parseInt(defaultTopicCount, 10),
+    recommendationWindowDays: Number.parseInt(defaultWindowDays, 10)
+  };
+
+  if (!options.defaults) {
+    if (!input.isTTY || !output.isTTY) {
+      throw new Error("Interactive setup requires a TTY. Re-run in a terminal or use --defaults.");
+    }
+
+    const rl = createInterface({ input, output });
+    try {
+      console.log("harulog setup");
+      console.log("Leave the Gemini key blank to keep the current value or use GEMINI_API_KEY from env.");
+      console.log("");
+
+      const geminiApiKeyInput = await askText(rl, "Gemini API key", "");
+      if (geminiApiKeyInput) {
+        nextConfig.geminiApiKey = geminiApiKeyInput;
+        nextConfig.geminiApiKeySource = "config";
+      } else if (!nextConfig.geminiApiKey) {
+        nextConfig.geminiApiKeySource = "env";
+      }
+
+      nextConfig.geminiModel = await askText(rl, "Gemini model", nextConfig.geminiModel ?? defaults.geminiModel);
+      nextConfig.codexHome = await askText(rl, "Codex home", defaultCodexHome);
+      nextConfig.localGitRepos = splitCsv(await askText(rl, "Tracked git repos (comma-separated, optional)", defaultRepos));
+      nextConfig.localGitScanRoots = splitCsv(
+        await askText(rl, "Git scan roots (comma-separated)", defaultScanRoots)
+      );
+      nextConfig.localGitScanDepth = Number.parseInt(
+        await askText(rl, "Git scan depth", defaultScanDepth),
+        10
+      );
+      nextConfig.schedule = {
+        weekday: Number.parseInt(await askText(rl, "Schedule weekday (0=Sun, 5=Fri)", defaultWeekday), 10),
+        hour: Number.parseInt(await askText(rl, "Schedule hour (0-23)", defaultHour), 10)
+      };
+      nextConfig.topicCount = Number.parseInt(await askText(rl, "Topic count", defaultTopicCount), 10);
+      nextConfig.recommendationWindowDays = Number.parseInt(
+        await askText(rl, "Recommendation window days", defaultWindowDays),
+        10
+      );
+
+      if (options.installScheduler === undefined && options.skipScheduler === undefined) {
+        shouldInstallScheduler = await askYesNo(rl, "Install launchd scheduler now?", true);
+      }
+    } finally {
+      rl.close();
+    }
+  }
+
+  await ensureDir(defaults.appHome);
+  await ensureDir(defaults.outputsDir);
+  await ensureDir(defaults.logsDir);
+  await ensureDir(defaults.binDir);
+  await saveUserConfig(nextConfig);
+
+  const resolved = await loadConfig();
+  console.log(`Saved config to ${resolved.configPath}`);
+
+  if (shouldInstallScheduler) {
+    const status = await installScheduler(resolved, {
+      writeOnly: options.writeOnlyScheduler === true
+    });
+    console.log(`Scheduler installed: ${status.plistPath}`);
+  }
+}

package/src/storage/history.ts

@@ -0,0 +1,28 @@
+import type { TopicHistoryItem, TopicSuggestion } from "../types";
+import { readJsonFile, writeJsonFile } from "../utils/file";
+
+export async function loadTopicHistory(filePath: string): Promise<TopicHistoryItem[]> {
+  return readJsonFile<TopicHistoryItem[]>(filePath, []);
+}
+
+export async function saveTopicHistory(filePath: string, history: TopicHistoryItem[]): Promise<void> {
+  await writeJsonFile(filePath, history);
+}
+
+export function mergeTopicHistory(
+  history: TopicHistoryItem[],
+  suggestions: TopicSuggestion[],
+  generatedAt: Date
+): TopicHistoryItem[] {
+  const merged = [...history];
+
+  for (const suggestion of suggestions) {
+    merged.push({
+      title: suggestion.title,
+      createdAt: generatedAt.toISOString(),
+      relatedKeywords: suggestion.keywords
+    });
+  }
+
+  return merged.slice(-100);
+}

package/src/storage/state.ts

@@ -0,0 +1,82 @@
+import type { RuntimeState } from "../types";
+import {
+  formatWeekdayLabel,
+  getMostRecentScheduledMomentForWeekday,
+  getScheduledMomentForWeekday,
+  isOnOrAfter
+} from "../utils/date";
+import { readJsonFile, writeJsonFile } from "../utils/file";
+
+export interface ScheduledRunDecision {
+  shouldRun: boolean;
+  reason: string;
+}
+
+export async function loadRuntimeState(filePath: string): Promise<RuntimeState> {
+  return readJsonFile<RuntimeState>(filePath, {});
+}
+
+export async function saveRuntimeState(filePath: string, state: RuntimeState): Promise<void> {
+  await writeJsonFile(filePath, state);
+}
+
+function buildScheduleLabel(weekday: number, scheduleHour: number): string {
+  return `${formatWeekdayLabel(weekday)} ${String(scheduleHour).padStart(2, "0")}:00`;
+}
+
+export function shouldRunScheduledJob(
+  now: Date,
+  scheduleWeekday: number,
+  scheduleHour: number,
+  state: RuntimeState,
+  force = false
+): ScheduledRunDecision {
+  if (force) {
+    return {
+      shouldRun: true,
+      reason: "Forced execution requested."
+    };
+  }
+
+  const currentWeekScheduledMoment = getScheduledMomentForWeekday(now, scheduleWeekday, scheduleHour);
+  const mostRecentScheduledMoment = getMostRecentScheduledMomentForWeekday(
+    now,
+    scheduleWeekday,
+    scheduleHour
+  );
+  const scheduleLabel = buildScheduleLabel(scheduleWeekday, scheduleHour);
+
+  if (!state.lastRunAt) {
+    if (!isOnOrAfter(now, currentWeekScheduledMoment)) {
+      return {
+        shouldRun: false,
+        reason: `Current time is before this week's scheduled run (${scheduleLabel}).`
+      };
+    }
+
+    return {
+      shouldRun: true,
+      reason: `No previous run found and this week's scheduled time has passed (${scheduleLabel}).`
+    };
+  }
+
+  const lastRunAt = new Date(state.lastRunAt);
+  if (!Number.isFinite(lastRunAt.getTime())) {
+    return {
+      shouldRun: true,
+      reason: "Stored state is invalid."
+    };
+  }
+
+  if (isOnOrAfter(lastRunAt, mostRecentScheduledMoment)) {
+    return {
+      shouldRun: false,
+      reason: `Job already ran for the latest scheduled window (${scheduleLabel}).`
+    };
+  }
+
+  return {
+    shouldRun: true,
+    reason: `Latest scheduled window passed and no run has been recorded for it (${scheduleLabel}).`
+  };
+}

package/src/types.ts

@@ -0,0 +1,61 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+
+export type ActivitySource = "github" | "git" | "codex";
+export type ActivityStatus = "done" | "planned" | "reference";
+export type LlmProvider = "gemini" | "placeholder";
+
+export interface ActivityItem {
+  id: string;
+  source: ActivitySource;
+  type: string;
+  title: string;
+  summary: string;
+  timestamp: string;
+  url?: string;
+  tags: string[];
+  weight: number;
+  status: ActivityStatus;
+  evidence: string[];
+  metadata?: Record<string, JsonValue>;
+}
+
+export interface TopicSuggestion {
+  title: string;
+  reason: string;
+  audience: string;
+  outline: string[];
+  draft: string;
+  keywords: string[];
+  evidenceIds: string[];
+  score: number;
+}
+
+export interface TopicHistoryItem {
+  title: string;
+  createdAt: string;
+  relatedKeywords: string[];
+}
+
+export interface RuntimeState {
+  lastRunAt?: string;
+  lastOutputJsonPath?: string;
+  lastOutputMarkdownPath?: string;
+}
+
+export interface DailyJobResult {
+  skipped: boolean;
+  reason: string;
+  suggestions: TopicSuggestion[];
+}
+
+export interface RecommendInput {
+  activities: ActivityItem[];
+  history: TopicHistoryItem[];
+  count: number;
+  now: Date;
+}
+
+export interface TopicRecommender {
+  recommend(input: RecommendInput): Promise<TopicSuggestion[]>;
+}

package/src/utils/date.ts

@@ -0,0 +1,47 @@
+export function formatLocalDateKey(date: Date): string {
+  const year = date.getFullYear();
+  const month = `${date.getMonth() + 1}`.padStart(2, "0");
+  const day = `${date.getDate()}`.padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+export function formatWeekdayLabel(weekday: number): string {
+  const labels = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+  return labels[weekday] ?? `weekday-${weekday}`;
+}
+
+export function subtractDays(date: Date, days: number): Date {
+  const next = new Date(date);
+  next.setDate(next.getDate() - days);
+  return next;
+}
+
+export function getScheduledMoment(date: Date, hour: number): Date {
+  const next = new Date(date);
+  next.setHours(hour, 0, 0, 0);
+  return next;
+}
+
+export function getScheduledMomentForWeekday(date: Date, weekday: number, hour: number): Date {
+  const next = new Date(date);
+  const dayOffset = weekday - next.getDay();
+  next.setDate(next.getDate() + dayOffset);
+  next.setHours(hour, 0, 0, 0);
+  return next;
+}
+
+export function getMostRecentScheduledMomentForWeekday(
+  date: Date,
+  weekday: number,
+  hour: number
+): Date {
+  const next = getScheduledMomentForWeekday(date, weekday, hour);
+  if (next.getTime() > date.getTime()) {
+    next.setDate(next.getDate() - 7);
+  }
+  return next;
+}
+
+export function isOnOrAfter(left: Date, right: Date): boolean {
+  return left.getTime() >= right.getTime();
+}

package/src/utils/file.ts

@@ -0,0 +1,47 @@
+import { access, chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+export async function ensureDir(dirPath: string): Promise<void> {
+  await mkdir(dirPath, { recursive: true });
+}
+
+export async function pathExists(targetPath: string): Promise<boolean> {
+  try {
+    await access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function readJsonFile<T>(filePath: string, fallback: T): Promise<T> {
+  try {
+    const content = await readFile(filePath, "utf8");
+    return JSON.parse(content) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+export async function writeJsonFile(filePath: string, value: unknown): Promise<void> {
+  await ensureDir(path.dirname(filePath));
+  await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+export async function writeTextFile(filePath: string, content: string): Promise<void> {
+  await ensureDir(path.dirname(filePath));
+  await writeFile(filePath, content, "utf8");
+}
+
+export async function writeExecutableFile(filePath: string, content: string): Promise<void> {
+  await writeTextFile(filePath, content);
+  await chmod(filePath, 0o755);
+}
+
+export async function removeFileIfExists(filePath: string): Promise<void> {
+  try {
+    await rm(filePath, { force: true });
+  } catch {
+    // best effort
+  }
+}