@giwonn/claude-daily-review 0.2.3 → 0.3.0

package/hooks/hooks.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/on-stop.js\"",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/on-stop.mjs\"",
             "async": true,
             "timeout": 10
           }
@@ -25,10 +25,11 @@
     ],
     "SessionStart": [
       {
+        "matcher": "startup",
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/on-session-start-check.js\"",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start-check",
             "timeout": 5
           }
         ]

package/hooks/on-stop.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// @ts-check
+import { loadConfig, createStorageAdapter } from '../lib/config.mjs';
+import { parseHookInput, appendRawLog } from '../lib/raw-logger.mjs';
+import { getRawDir } from '../lib/vault.mjs';
+import { formatDate } from '../lib/periods.mjs';
+
+async function main() {
+  try {
+    const config = loadConfig();
+    if (!config) return;
+    const storage = await createStorageAdapter(config);
+    let data = '';
+    process.stdin.setEncoding('utf-8');
+    for await (const chunk of process.stdin) { data += chunk; }
+    const input = parseHookInput(data);
+    const sessionDir = getRawDir(input.session_id);
+    const date = formatDate(new Date());
+    await appendRawLog(storage, sessionDir, date, input);
+  } catch {
+    // async hook — fail silently
+  }
+}
+main();

package/hooks/run-hook.cmd

@@ -0,0 +1,27 @@
+: << 'CMDBLOCK'
+@echo off
+if "%~1"=="" (
+    echo run-hook.cmd: missing script name >&2
+    exit /b 1
+)
+set "HOOK_DIR=%~dp0"
+if exist "C:\Program Files\Git\bin\bash.exe" (
+    "C:\Program Files\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+if exist "C:\Program Files (x86)\Git\bin\bash.exe" (
+    "C:\Program Files (x86)\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+where bash >nul 2>nul
+if %ERRORLEVEL% equ 0 (
+    bash "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+exit /b 0
+CMDBLOCK
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SCRIPT_NAME="$1"
+shift
+exec bash "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"

package/hooks/session-start-check

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+result=$(node -e "
+import { loadConfig } from '${PLUGIN_ROOT}/lib/config.mjs';
+try {
+  const config = loadConfig();
+  if (!config) process.stdout.write('NEEDS_SETUP');
+} catch {
+  process.stdout.write('NEEDS_SETUP');
+}
+" 2>/dev/null || echo "NEEDS_SETUP")
+
+if [ "$result" = "NEEDS_SETUP" ]; then
+  msg='<important-reminder>IN YOUR FIRST REPLY YOU MUST TELL THE USER: daily-review 플러그인이 아직 설정되지 않았습니다. /daily-review-setup 을 실행해주세요.</important-reminder>'
+
+  if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ]; then
+    printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\n' "$msg"
+  else
+    printf '{"additional_context":"%s"}\n' "$msg"
+  fi
+fi
+
+exit 0

package/lib/config.mjs

@@ -0,0 +1,122 @@
+// @ts-check
+/** @typedef {import('./types.d.ts').Config} Config */
+/** @typedef {import('./types.d.ts').StorageAdapter} StorageAdapter */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { LocalStorageAdapter } from './storage.mjs';
+
+/** @returns {string} */
+export function getConfigPath() {
+  const dataDir = process.env.CLAUDE_PLUGIN_DATA;
+  if (!dataDir) {
+    throw new Error('CLAUDE_PLUGIN_DATA environment variable is not set');
+  }
+  return join(dataDir, 'config.json');
+}
+
+/**
+ * @param {unknown} raw
+ * @returns {raw is { vaultPath: string; reviewFolder: string; language: string; periods: any; profile: any }}
+ */
+function isOldConfig(raw) {
+  if (!raw || typeof raw !== 'object') return false;
+  return 'vaultPath' in raw && 'reviewFolder' in raw;
+}
+
+/**
+ * @param {{ vaultPath: string; reviewFolder: string; language: string; periods: any; profile: any }} old
+ * @returns {Config}
+ */
+function migrateOldConfig(old) {
+  return {
+    storage: {
+      type: 'local',
+      local: { basePath: join(old.vaultPath, old.reviewFolder) },
+    },
+    language: old.language,
+    periods: old.periods,
+    profile: old.profile,
+  };
+}
+
+/** @returns {Config | null} */
+export function loadConfig() {
+  const configPath = getConfigPath();
+  if (!existsSync(configPath)) return null;
+  const raw = JSON.parse(readFileSync(configPath, 'utf-8'));
+  if (isOldConfig(raw)) {
+    const migrated = migrateOldConfig(raw);
+    saveConfig(migrated);
+    return migrated;
+  }
+  return /** @type {Config} */ (raw);
+}
+
+/** @param {Config} config */
+export function saveConfig(config) {
+  const configPath = getConfigPath();
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+}
+
+/**
+ * @param {unknown} config
+ * @returns {config is Config}
+ */
+export function validateConfig(config) {
+  if (!config || typeof config !== 'object') return false;
+  const c = /** @type {Record<string, unknown>} */ (config);
+  if (!c.storage || typeof c.storage !== 'object') return false;
+  const s = /** @type {Record<string, unknown>} */ (c.storage);
+  if (s.type !== 'local' && s.type !== 'github') return false;
+  if (s.type === 'local') {
+    if (!s.local || typeof s.local !== 'object') return false;
+    const l = /** @type {Record<string, unknown>} */ (s.local);
+    if (typeof l.basePath !== 'string' || l.basePath === '') return false;
+  }
+  if (s.type === 'github') {
+    if (!s.github || typeof s.github !== 'object') return false;
+    const g = /** @type {Record<string, unknown>} */ (s.github);
+    if (typeof g.owner !== 'string' || !g.owner) return false;
+    if (typeof g.repo !== 'string' || !g.repo) return false;
+    if (typeof g.token !== 'string' || !g.token) return false;
+  }
+  return true;
+}
+
+/** @param {string} basePath @returns {Config} */
+export function createDefaultLocalConfig(basePath) {
+  return {
+    storage: { type: 'local', local: { basePath } },
+    language: 'ko',
+    periods: { daily: true, weekly: true, monthly: true, quarterly: true, yearly: false },
+    profile: { company: '', role: '', team: '', context: '' },
+  };
+}
+
+/** @param {string} owner @param {string} repo @param {string} token @returns {Config} */
+export function createDefaultGitHubConfig(owner, repo, token) {
+  return {
+    storage: { type: 'github', github: { owner, repo, token, basePath: 'daily-review' } },
+    language: 'ko',
+    periods: { daily: true, weekly: true, monthly: true, quarterly: true, yearly: false },
+    profile: { company: '', role: '', team: '', context: '' },
+  };
+}
+
+/**
+ * @param {Config} config
+ * @returns {Promise<StorageAdapter>}
+ */
+export async function createStorageAdapter(config) {
+  if (config.storage.type === 'local') {
+    return new LocalStorageAdapter(config.storage.local.basePath);
+  }
+  if (config.storage.type === 'github') {
+    const { GitHubStorageAdapter } = await import('./github-storage.mjs');
+    const g = config.storage.github;
+    return new GitHubStorageAdapter(g.owner, g.repo, g.token, g.basePath);
+  }
+  throw new Error(`Unknown storage type: ${config.storage.type}`);
+}

package/lib/github-auth.mjs

@@ -0,0 +1,44 @@
+// @ts-check
+/** @typedef {import('./types.d.ts').DeviceCodeResponse} DeviceCodeResponse */
+
+const GITHUB_CLIENT_ID = 'Ov23lijFU2NkxD93Q2f2';
+
+/** @returns {Promise<DeviceCodeResponse>} */
+export async function requestDeviceCode() {
+  const res = await fetch('https://github.com/login/device/code', {
+    method: 'POST',
+    headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+    body: JSON.stringify({ client_id: GITHUB_CLIENT_ID, scope: 'repo' }),
+  });
+  if (!res.ok) throw new Error(`GitHub device code request failed: ${res.status}`);
+  return /** @type {Promise<DeviceCodeResponse>} */ (res.json());
+}
+
+/** @param {number} ms @returns {Promise<void>} */
+function sleep(ms) { return new Promise((resolve) => setTimeout(resolve, ms)); }
+
+/** @param {DeviceCodeResponse} deviceCode @param {number} [maxAttempts=180] @returns {Promise<string>} */
+export async function pollForToken(deviceCode, maxAttempts = 180) {
+  let interval = deviceCode.interval * 1000;
+  for (let i = 0; i < maxAttempts; i++) {
+    if (interval > 0) await sleep(interval);
+    const res = await fetch('https://github.com/login/oauth/access_token', {
+      method: 'POST',
+      headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        client_id: GITHUB_CLIENT_ID,
+        device_code: deviceCode.device_code,
+        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+      }),
+    });
+    /** @type {Record<string, unknown>} */
+    let data;
+    try { data = /** @type {Record<string, unknown>} */ (await res.json()); }
+    catch { continue; }
+    if (data.access_token) return /** @type {string} */ (data.access_token);
+    if (data.error === 'slow_down') { interval += 5000; continue; }
+    if (data.error === 'authorization_pending') continue;
+    throw new Error(`GitHub auth error: ${data.error}`);
+  }
+  throw new Error('GitHub auth timed out waiting for authorization');
+}

package/lib/github-storage.mjs

@@ -0,0 +1,81 @@
+// @ts-check
+/** @typedef {import('./types.d.ts').StorageAdapter} StorageAdapter */
+
+/** @implements {StorageAdapter} */
+export class GitHubStorageAdapter {
+  /** @param {string} owner @param {string} repo @param {string} token @param {string} basePath */
+  constructor(owner, repo, token, basePath) {
+    /** @private */ this.baseUrl = `https://api.github.com/repos/${owner}/${repo}/contents`;
+    /** @private */ this.basePath = basePath;
+    /** @private */ this.headers = {
+      Authorization: `Bearer ${token}`,
+      Accept: 'application/vnd.github.v3+json',
+      'Content-Type': 'application/json',
+    };
+  }
+
+  /** @private @param {string} path @returns {string} */
+  getUrl(path) { return `${this.baseUrl}/${this.basePath}/${path}`; }
+
+  /** @private @param {string} path @returns {Promise<string | null>} */
+  async getSha(path) {
+    const res = await fetch(this.getUrl(path), { method: 'GET', headers: this.headers });
+    if (res.status === 404) return null;
+    const data = /** @type {Record<string, unknown>} */ (await res.json());
+    return /** @type {string | null} */ (data.sha || null);
+  }
+
+  /** @param {string} path @returns {Promise<string | null>} */
+  async read(path) {
+    const res = await fetch(this.getUrl(path), { method: 'GET', headers: this.headers });
+    if (res.status === 404) return null;
+    const data = /** @type {Record<string, unknown>} */ (await res.json());
+    return Buffer.from(/** @type {string} */ (data.content), 'base64').toString('utf-8');
+  }
+
+  /** @param {string} path @param {string} content @returns {Promise<void>} */
+  async write(path, content) {
+    const sha = await this.getSha(path);
+    /** @type {Record<string, unknown>} */
+    const body = { message: `update ${path}`, content: Buffer.from(content).toString('base64') };
+    if (sha) body.sha = sha;
+    const res = await fetch(this.getUrl(path), { method: 'PUT', headers: this.headers, body: JSON.stringify(body) });
+    if (!res.ok && res.status === 409) {
+      const freshSha = await this.getSha(path);
+      if (freshSha) body.sha = freshSha;
+      await fetch(this.getUrl(path), { method: 'PUT', headers: this.headers, body: JSON.stringify(body) });
+    }
+  }
+
+  /** @param {string} path @param {string} content @returns {Promise<void>} */
+  async append(path, content) {
+    const existing = await this.read(path);
+    await this.write(path, existing ? existing + content : content);
+  }
+
+  /** @param {string} path @returns {Promise<boolean>} */
+  async exists(path) {
+    const res = await fetch(this.getUrl(path), { method: 'GET', headers: this.headers });
+    return res.status !== 404;
+  }
+
+  /** @param {string} dir @returns {Promise<string[]>} */
+  async list(dir) {
+    const res = await fetch(this.getUrl(dir), { method: 'GET', headers: this.headers });
+    if (res.status === 404) return [];
+    const data = await res.json();
+    if (!Array.isArray(data)) return [];
+    return data.map((/** @type {{ name: string }} */ entry) => entry.name);
+  }
+
+  /** @param {string} _dir @returns {Promise<void>} */
+  async mkdir(_dir) { /* GitHub creates directories implicitly */ }
+
+  /** @param {string} path @returns {Promise<boolean>} */
+  async isDirectory(path) {
+    const res = await fetch(this.getUrl(path), { method: 'GET', headers: this.headers });
+    if (res.status === 404) return false;
+    const data = await res.json();
+    return Array.isArray(data);
+  }
+}

package/lib/merge.mjs

@@ -0,0 +1,51 @@
+// @ts-check
+/** @typedef {import('./types.d.ts').StorageAdapter} StorageAdapter */
+
+/** @param {StorageAdapter} storage @param {string} rawDir @returns {Promise<string[]>} */
+export async function findUnprocessedSessions(storage, rawDir) {
+  if (!(await storage.exists(rawDir))) return [];
+  const entries = await storage.list(rawDir);
+  const results = [];
+  for (const entry of entries) {
+    const entryPath = `${rawDir}/${entry}`;
+    if (!(await storage.isDirectory(entryPath))) continue;
+    if (await storage.exists(`${entryPath}/.completed`)) continue;
+    results.push(entry);
+  }
+  return results;
+}
+
+/** @param {StorageAdapter} storage @param {string} reviewsDir @returns {Promise<string[]>} */
+export async function findPendingReviews(storage, reviewsDir) {
+  if (!(await storage.exists(reviewsDir))) return [];
+  const entries = await storage.list(reviewsDir);
+  return entries.filter((f) => f.endsWith('.md'));
+}
+
+/** @param {StorageAdapter} storage @param {string} sessionDir @returns {Promise<void>} */
+export async function markSessionCompleted(storage, sessionDir) {
+  await storage.write(`${sessionDir}/.completed`, new Date().toISOString());
+}
+
+/** @param {StorageAdapter} storage @param {string} sessionDir @returns {Promise<boolean>} */
+export async function isSessionCompleted(storage, sessionDir) {
+  return storage.exists(`${sessionDir}/.completed`);
+}
+
+/** @param {StorageAdapter} storage @param {string[]} reviewPaths @param {string} dailyPath @returns {Promise<void>} */
+export async function mergeReviewsIntoDaily(storage, reviewPaths, dailyPath) {
+  const reviewContents = [];
+  for (const p of reviewPaths) {
+    const content = await storage.read(p);
+    if (content && content.trim().length > 0) reviewContents.push(content.trim());
+  }
+  if (reviewContents.length === 0) {
+    if (!(await storage.exists(dailyPath))) await storage.write(dailyPath, '');
+    return;
+  }
+  const existing = await storage.read(dailyPath);
+  const merged = existing
+    ? existing.trimEnd() + '\n\n' + reviewContents.join('\n\n') + '\n'
+    : reviewContents.join('\n\n') + '\n';
+  await storage.write(dailyPath, merged);
+}

package/lib/periods.mjs

@@ -0,0 +1,82 @@
+// @ts-check
+
+/** @param {Date} date @returns {number} */
+export function getISOWeek(date) {
+  const d = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()));
+  const dayNum = d.getUTCDay() || 7;
+  d.setUTCDate(d.getUTCDate() + 4 - dayNum);
+  const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
+  return Math.ceil(((d.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
+}
+
+/** @param {Date} date @returns {number} */
+export function getISOWeekYear(date) {
+  const d = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()));
+  const dayNum = d.getUTCDay() || 7;
+  d.setUTCDate(d.getUTCDate() + 4 - dayNum);
+  return d.getUTCFullYear();
+}
+
+/** @param {Date} date @returns {number} */
+export function getQuarter(date) {
+  return Math.ceil((date.getMonth() + 1) / 3);
+}
+
+/** @param {Date} date @returns {string} */
+export function formatDate(date) {
+  const y = date.getFullYear();
+  const m = String(date.getMonth() + 1).padStart(2, '0');
+  const d = String(date.getDate()).padStart(2, '0');
+  return `${y}-${m}-${d}`;
+}
+
+/** @param {Date} date @returns {string} */
+export function formatWeek(date) {
+  return `${getISOWeekYear(date)}-W${String(getISOWeek(date)).padStart(2, '0')}`;
+}
+
+/** @param {Date} date @returns {string} */
+export function formatMonth(date) {
+  return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}`;
+}
+
+/** @param {Date} date @returns {string} */
+export function formatQuarter(date) {
+  return `${date.getFullYear()}-Q${getQuarter(date)}`;
+}
+
+/** @param {Date} date @returns {string} */
+export function formatYear(date) {
+  return `${date.getFullYear()}`;
+}
+
+/**
+ * @param {Date} today
+ * @param {Date | null} lastRun
+ * @returns {{ needsWeekly: boolean, needsMonthly: boolean, needsQuarterly: boolean, needsYearly: boolean, previousWeek: string, previousMonth: string, previousQuarter: string, previousYear: string }}
+ */
+export function checkPeriodsNeeded(today, lastRun) {
+  if (!lastRun) {
+    return {
+      needsWeekly: false, needsMonthly: false, needsQuarterly: false, needsYearly: false,
+      previousWeek: '', previousMonth: '', previousQuarter: '', previousYear: '',
+    };
+  }
+  const todayWeek = formatWeek(today);
+  const lastWeek = formatWeek(lastRun);
+  const todayMonth = formatMonth(today);
+  const lastMonth = formatMonth(lastRun);
+  const todayQuarter = formatQuarter(today);
+  const lastQuarter = formatQuarter(lastRun);
+  const todayYear = formatYear(today);
+  const lastYear = formatYear(lastRun);
+
+  return {
+    needsWeekly: todayWeek !== lastWeek,
+    needsMonthly: todayMonth !== lastMonth,
+    needsQuarterly: todayQuarter !== lastQuarter,
+    needsYearly: todayYear !== lastYear,
+    previousWeek: lastWeek, previousMonth: lastMonth,
+    previousQuarter: lastQuarter, previousYear: lastYear,
+  };
+}

package/lib/raw-logger.mjs

@@ -0,0 +1,19 @@
+// @ts-check
+/** @typedef {import('./types.d.ts').StorageAdapter} StorageAdapter */
+/** @typedef {import('./types.d.ts').HookInput} HookInput */
+
+/** @param {string} raw @returns {HookInput} */
+export function parseHookInput(raw) {
+  const parsed = JSON.parse(raw);
+  if (!parsed || typeof parsed !== 'object') throw new Error('Invalid hook input: expected object');
+  if (typeof parsed.session_id !== 'string' || !parsed.session_id) throw new Error('Invalid hook input: missing session_id');
+  return /** @type {HookInput} */ (parsed);
+}
+
+/** @param {StorageAdapter} storage @param {string} sessionDir @param {string} date @param {HookInput} entry @returns {Promise<void>} */
+export async function appendRawLog(storage, sessionDir, date, entry) {
+  await storage.mkdir(sessionDir);
+  const logPath = `${sessionDir}/${date}.jsonl`;
+  const record = { ...entry, timestamp: new Date().toISOString() };
+  await storage.append(logPath, JSON.stringify(record) + '\n');
+}

package/lib/storage-cli.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// @ts-check
+import { loadConfig, createStorageAdapter } from './config.mjs';
+
+async function main() {
+  const [command, ...args] = process.argv.slice(2);
+  const config = loadConfig();
+  if (!config) { process.stderr.write('config not found\n'); process.exit(1); }
+
+  const storage = await createStorageAdapter(config);
+
+  switch (command) {
+    case 'read': {
+      const content = await storage.read(args[0]);
+      if (content !== null) process.stdout.write(content);
+      break;
+    }
+    case 'write': {
+      let data = '';
+      process.stdin.setEncoding('utf-8');
+      for await (const chunk of process.stdin) { data += chunk; }
+      await storage.write(args[0], data);
+      break;
+    }
+    case 'append': {
+      let data = '';
+      process.stdin.setEncoding('utf-8');
+      for await (const chunk of process.stdin) { data += chunk; }
+      await storage.append(args[0], data);
+      break;
+    }
+    case 'list': {
+      const entries = await storage.list(args[0]);
+      process.stdout.write(entries.join('\n') + '\n');
+      break;
+    }
+    case 'exists': {
+      const exists = await storage.exists(args[0]);
+      process.stdout.write(exists ? 'true\n' : 'false\n');
+      process.exit(exists ? 0 : 1);
+      break;
+    }
+    default:
+      process.stderr.write(`Unknown command: ${command}\nUsage: storage-cli <read|write|append|list|exists> <path>\n`);
+      process.exit(1);
+  }
+}
+main().catch((err) => { process.stderr.write(`Error: ${err.message}\n`); process.exit(1); });

package/lib/storage.mjs

@@ -0,0 +1,63 @@
+// @ts-check
+/** @typedef {import('./types.d.ts').StorageAdapter} StorageAdapter */
+
+import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'fs';
+import { dirname, join } from 'path';
+
+/** @implements {StorageAdapter} */
+export class LocalStorageAdapter {
+  /** @param {string} basePath */
+  constructor(basePath) {
+    /** @private */
+    this.basePath = basePath;
+  }
+
+  /** @private @param {string} path @returns {string} */
+  resolve(path) {
+    return join(this.basePath, path);
+  }
+
+  /** @param {string} path @returns {Promise<string | null>} */
+  async read(path) {
+    const full = this.resolve(path);
+    if (!existsSync(full)) return null;
+    return readFileSync(full, 'utf-8');
+  }
+
+  /** @param {string} path @param {string} content @returns {Promise<void>} */
+  async write(path, content) {
+    const full = this.resolve(path);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, content, 'utf-8');
+  }
+
+  /** @param {string} path @param {string} content @returns {Promise<void>} */
+  async append(path, content) {
+    const full = this.resolve(path);
+    mkdirSync(dirname(full), { recursive: true });
+    appendFileSync(full, content, 'utf-8');
+  }
+
+  /** @param {string} path @returns {Promise<boolean>} */
+  async exists(path) {
+    return existsSync(this.resolve(path));
+  }
+
+  /** @param {string} dir @returns {Promise<string[]>} */
+  async list(dir) {
+    const full = this.resolve(dir);
+    if (!existsSync(full)) return [];
+    return readdirSync(full);
+  }
+
+  /** @param {string} dir @returns {Promise<void>} */
+  async mkdir(dir) {
+    mkdirSync(this.resolve(dir), { recursive: true });
+  }
+
+  /** @param {string} path @returns {Promise<boolean>} */
+  async isDirectory(path) {
+    try { return statSync(this.resolve(path)).isDirectory(); }
+    catch { return false; }
+  }
+}

package/lib/types.d.ts

@@ -0,0 +1,64 @@
+export interface Profile {
+  company: string;
+  role: string;
+  team: string;
+  context: string;
+}
+
+export interface Periods {
+  daily: true;
+  weekly: boolean;
+  monthly: boolean;
+  quarterly: boolean;
+  yearly: boolean;
+}
+
+export interface LocalStorageConfig {
+  basePath: string;
+}
+
+export interface GitHubStorageConfig {
+  owner: string;
+  repo: string;
+  token: string;
+  basePath: string;
+}
+
+export interface StorageConfig {
+  type: "local" | "github";
+  local?: LocalStorageConfig;
+  github?: GitHubStorageConfig;
+}
+
+export interface Config {
+  storage: StorageConfig;
+  language: string;
+  periods: Periods;
+  profile: Profile;
+}
+
+export interface StorageAdapter {
+  read(path: string): Promise<string | null>;
+  write(path: string, content: string): Promise<void>;
+  append(path: string, content: string): Promise<void>;
+  exists(path: string): Promise<boolean>;
+  list(dir: string): Promise<string[]>;
+  mkdir(dir: string): Promise<void>;
+  isDirectory(path: string): Promise<boolean>;
+}
+
+export interface HookInput {
+  session_id: string;
+  transcript_path: string;
+  cwd: string;
+  hook_event_name: string;
+  [key: string]: unknown;
+}
+
+export interface DeviceCodeResponse {
+  device_code: string;
+  user_code: string;
+  verification_uri: string;
+  expires_in: number;
+  interval: number;
+}