change-log-agent 1.0.0 → 1.1.0

package/README.md

@@ -1,89 +1,117 @@
-# 🤖 log-agent
+# change-log-agent
 
-> **"讓 AI 成為你的專案文件官：一鍵同步 Git Commit 到高品質開發文件。"**
+> **Turn messy git commits into polished project documentation with a single command.**
 
-`log-agent` 是一款基於 **Agentic Workflow** 設計的 CLI 工具。它不只是簡單的文字搬運工，而是透過驅動你本地的 **Claude Code** 實例，將混亂的 Git Commit 歷史轉化為結構清晰、具備「人味」的專案文件（如 README 或 CHANGELOG）。
+`change-log-agent` is a CLI tool built on an **agent-based workflow**. Rather than simply copying text, it drives your local **Claude Code** instance to transform raw git commit history into well-structured, human-readable documentation (README, CHANGELOG, etc.).
 
 ---
 
-## ✨ 核心亮點
+## Highlights
 
-- **💰 零 API 成本**：直接利用你現有的 Claude Pro/Team 訂閱，無需支付額外 API Tokens 費用。
-- **🧠 代理人架構 (Agentic Workflow)**：CLI 會動態生成任務規範（Mission Spec），指揮 AI 自主決定如何最佳化文件內容。
-- **🎯 Surgical 級精準修改**：透過 HTML 註釋標記（`<!-- log-agent-start -->` / `<!-- log-agent-end -->`）定位，確保 AI 只修改授權區塊，絕不破壞你的原始文件排版。
-- **⚙️ 語境感知 (Context-Aware)**：自動過濾碎屑 Commit（如 typo、formatting），並根據專案背景（如：官網重構）進行智能歸納。
+- **Zero API Cost** — Uses your existing Claude Pro/Team subscription. No extra API token charges.
+- **Agent-Based Workflow** — Dynamically generates a Mission Spec and lets the AI decide how to best organize your documentation.
+- **Surgical Precision** — Uses HTML comment markers (`<!-- log-agent-start -->` / `<!-- log-agent-end -->`) to scope changes. Only the marked section is modified; the rest of your file stays untouched.
+- **Incremental Sync** — Automatically detects the last update date from the marked section, fetching only new commits to avoid redundant processing.
+- **Context-Aware** — Filters out trivial commits (typos, formatting) and intelligently summarizes changes based on project context.
 
 ---
 
-## 🛠️ 運作原理
+## How It Works
 
-1. **萃取 (Extract)**：CLI 自動掃描 Git 歷史，鎖定自上次版本以來的變更。
-2. **策劃 (Plan)**：根據專案現狀動態生成一份暫時的 `.claudemd.tmp` 任務規範。
-3. **執行 (Execute)**：啟動 `claude-code` 擔任「執行官」，依照規範對目標檔案進行智能手術。
-4. **清理 (Cleanup)**：任務完成後自動銷毀暫存檔，不留痕跡。
+1. **Detect** — Scans the target file for marker tags and identifies the last sync date.
+2. **Extract** — Fetches new commits from git history since the last sync.
+3. **Plan** — Generates a Mission Spec describing how the AI should update the document.
+4. **Execute** — Invokes `claude -p` to apply precise edits to the target file.
 
 ---
 
-## 🚀 快速開始
+## Getting Started
 
-### 1. 前置要求
+### Prerequisites
 
-- 已安裝 **Node.js** (v18+)
-- 已安裝並登入 **Claude Code**：
+- **Node.js** v18+
+- **Claude Code** installed and authenticated:
 
   ```bash
   npm install -g @anthropic-ai/claude-code
   claude login
   ```
 
-### 2. 安裝與開發
+### Install
 
 ```bash
-# 克隆專案
-git clone https://github.com/your-username/log-agent.git
-cd log-agent
-
-# 安裝依賴
-npm install
-
-# 編譯
-npm run build
+npm install -g change-log-agent
 ```
 
-### 3. 初始化目標文件
+### Prepare Your Target File
 
-在你的 `README.md` 或 `CHANGELOG.md` 中加入以下標記：
+Add the following markers to your `README.md` or `CHANGELOG.md`:
 
 ```markdown
-## 📝 更新日誌
+## Changelog
 
 <!-- log-agent-start -->
 <!-- log-agent-end -->
 ```
 
-### 4. 執行同步
+### Run
+
+```bash
+# Basic usage — auto-detects date, updates README.md
+log-agent sync
+
+# Specify a start date
+log-agent sync --since 2026-02-01
+
+# Target a different file
+log-agent sync --target CHANGELOG.md
+
+# Preview mode — prints Mission Spec without executing
+log-agent sync --dry-run
+```
+
+Or run without installing:
 
 ```bash
-# 使用本地開發版本測試
-npx ts-node src/index.ts sync
+npx change-log-agent sync
 ```
 
+### CLI Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--since <date>` | Only include commits after this date | Auto-detected from markers |
+| `--target <file>` | File to update | `README.md` |
+| `--dry-run` | Preview the Mission Spec without executing | `false` |
+
 ---
 
-## 📂 專案結構
+## Project Structure
 
-- `src/core/git.ts`：負責處理 Git 指令與 Log 提取。
-- `src/core/template.ts`：動態任務規範 (Mission Spec) 生成器。
-- `src/index.ts`：CLI 入口與流程調度中心。
+| File | Responsibility |
+|------|----------------|
+| `src/index.ts` | CLI entry point and orchestration |
+| `src/core/git.ts` | Git commands and commit log extraction |
+| `src/core/template.ts` | Mission Spec generation |
+| `src/core/bridge.ts` | Claude Code bridge (`claude -p` invocation) |
+| `src/core/marker.ts` | Marker detection and date extraction |
 
 ---
 
-## 🤝 貢獻與開發
+## Contributing
+
+```bash
+git clone https://github.com/ericcai0814/change-log-agent.git
+cd change-log-agent
+npm install
+npm run build
+npm test
+```
 
-本專案目前專注於與 `claude-code` 的深度整合。如果你有任何關於 Prompt 優化或跨平台相容性的建議，歡迎提交 Issue 或 Pull Request！
+Issues and pull requests are welcome!
 
 ---
 
-License
+## License
 
-MIT License - see LICENSE file for details
+MIT — see [LICENSE](LICENSE) for details.

package/dist/index.mjs

@@ -2,7 +2,9 @@
 import { Command } from "commander";
 import chalk from "chalk";
 import { execa } from "execa";
-import { readFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
 
 //#region src/core/git.ts
 /**
@@ -101,19 +103,29 @@ async function checkMarkers(filePath) {
 		const lastDate = hasStart && hasEnd ? extractLastDate(content) : void 0;
 		return {
 			found: hasStart && hasEnd,
+			fileExists: true,
 			lastDate,
 			startTag: START_TAG,
 			endTag: END_TAG
 		};
-	} catch {
+	} catch (error) {
 		return {
 			found: false,
+			fileExists: !(error instanceof Error && "code" in error && error.code === "ENOENT"),
 			lastDate: void 0,
 			startTag: START_TAG,
 			endTag: END_TAG
 		};
 	}
 }
+const MARKER_TEMPLATE = `# Changelog
+
+${START_TAG}
+${END_TAG}
+`;
+async function createMarkerFile(filePath) {
+	await writeFile(filePath, MARKER_TEMPLATE, "utf-8");
+}
 function extractLastDate(content) {
 	const startIdx = content.indexOf(START_TAG);
 	const endIdx = content.indexOf(END_TAG);
@@ -121,16 +133,39 @@ function extractLastDate(content) {
 	return [...content.slice(startIdx, endIdx).matchAll(/###\s+(\d{4}-\d{2}-\d{2})/g)].map((m) => m[1]).filter((d) => d !== void 0).sort().at(-1);
 }
 
+//#endregion
+//#region src/utils/prompt.ts
+async function confirmPrompt(message) {
+	const rl = createInterface({
+		input: stdin,
+		output: stdout
+	});
+	try {
+		const trimmed = (await rl.question(`${message} (Y/n) `)).trim().toLowerCase();
+		return trimmed === "" || trimmed === "y";
+	} finally {
+		rl.close();
+	}
+}
+
 //#endregion
 //#region src/index.ts
 const program = new Command();
 program.name("log-agent").description("AI-Powered Agentic Documentation CLI").version("0.1.0");
-program.command("sync").description("Sync git log to documentation").option("--since <date>", "Only include commits after this date (e.g. 2026-02-01)").option("--target <file>", "Target file to update", "README.md").option("--dry-run", "Preview the mission spec without executing", false).action(async (options) => {
-	const { target: targetFile, since, dryRun } = options;
+async function syncAction(options) {
+	const { target: targetFile, since, dryRun, yes: autoYes } = options;
 	try {
 		console.log(chalk.blue("Starting log-agent sync..."));
 		const markers = await checkMarkers(targetFile);
-		if (!dryRun && !markers.found) {
+		if (!dryRun && !markers.found) if (!markers.fileExists) {
+			if (!(autoYes || await confirmPrompt(`${targetFile} not found. Create it?`))) {
+				console.error(chalk.red("Aborted."));
+				process.exitCode = 1;
+				return;
+			}
+			await createMarkerFile(targetFile);
+			console.log(chalk.green(`Created ${targetFile} with markers.`));
+		} else {
 			console.error(chalk.red(`Markers not found in ${targetFile}.`));
 			console.error(chalk.gray(`Add these lines to your file:\n  ${markers.startTag}\n  ${markers.endTag}`));
 			process.exitCode = 1;
@@ -164,8 +199,9 @@ program.command("sync").description("Sync git log to documentation").option("--s
 		else console.error(chalk.red(`Sync failed: ${message}`));
 		process.exitCode = 1;
 	}
-});
+}
+program.command("sync").description("Sync git log to documentation").option("--since <date>", "Only include commits after this date (e.g. 2026-02-01)").option("--target <file>", "Target file to update", "CHANGELOG.md").option("--dry-run", "Preview the mission spec without executing", false).option("--yes", "Skip interactive confirmation (for CI/CD)", false).action(syncAction);
 program.parse();
 
 //#endregion
-export {  };
+export { syncAction };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "change-log-agent",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "AI-powered CLI that syncs git commit history to project documentation via Claude Code",
   "type": "module",
   "main": "dist/index.mjs",
@@ -27,7 +27,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ericcai0814/log-agent.git"
+    "url": "git+https://github.com/ericcai0814/change-log-agent.git"
   },
   "dependencies": {
     "chalk": "^5.6.2",