change-log-agent 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jesse Vincent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# 🤖 log-agent
+
+> **"讓 AI 成為你的專案文件官：一鍵同步 Git Commit 到高品質開發文件。"**
+
+`log-agent` 是一款基於 **Agentic Workflow** 設計的 CLI 工具。它不只是簡單的文字搬運工，而是透過驅動你本地的 **Claude Code** 實例，將混亂的 Git Commit 歷史轉化為結構清晰、具備「人味」的專案文件（如 README 或 CHANGELOG）。
+
+---
+
+## ✨ 核心亮點
+
+- **💰 零 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），並根據專案背景（如：官網重構）進行智能歸納。
+
+---
+
+## 🛠️ 運作原理
+
+1. **萃取 (Extract)**：CLI 自動掃描 Git 歷史，鎖定自上次版本以來的變更。
+2. **策劃 (Plan)**：根據專案現狀動態生成一份暫時的 `.claudemd.tmp` 任務規範。
+3. **執行 (Execute)**：啟動 `claude-code` 擔任「執行官」，依照規範對目標檔案進行智能手術。
+4. **清理 (Cleanup)**：任務完成後自動銷毀暫存檔，不留痕跡。
+
+---
+
+## 🚀 快速開始
+
+### 1. 前置要求
+
+- 已安裝 **Node.js** (v18+)
+- 已安裝並登入 **Claude Code**：
+
+  ```bash
+  npm install -g @anthropic-ai/claude-code
+  claude login
+  ```
+
+### 2. 安裝與開發
+
+```bash
+# 克隆專案
+git clone https://github.com/your-username/log-agent.git
+cd log-agent
+
+# 安裝依賴
+npm install
+
+# 編譯
+npm run build
+```
+
+### 3. 初始化目標文件
+
+在你的 `README.md` 或 `CHANGELOG.md` 中加入以下標記：
+
+```markdown
+## 📝 更新日誌
+
+<!-- log-agent-start -->
+<!-- log-agent-end -->
+```
+
+### 4. 執行同步
+
+```bash
+# 使用本地開發版本測試
+npx ts-node src/index.ts sync
+```
+
+---
+
+## 📂 專案結構
+
+- `src/core/git.ts`：負責處理 Git 指令與 Log 提取。
+- `src/core/template.ts`：動態任務規範 (Mission Spec) 生成器。
+- `src/index.ts`：CLI 入口與流程調度中心。
+
+---
+
+## 🤝 貢獻與開發
+
+本專案目前專注於與 `claude-code` 的深度整合。如果你有任何關於 Prompt 優化或跨平台相容性的建議，歡迎提交 Issue 或 Pull Request！
+
+---
+
+License
+
+MIT License - see LICENSE file for details

package/dist/index.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import chalk from "chalk";
+import { execa } from "execa";
+import { readFile } from "node:fs/promises";
+
+//#region src/core/git.ts
+/**
+* 擷取 git log 並 parse 成結構化資料
+* @param since - ISO date string, e.g. "2026-02-01"
+*/
+async function getCommits(since) {
+	const { stdout } = await execa("git", [
+		"log",
+		"--pretty=format:%h|%an|%ai|%s",
+		...since ? [`--since=${since}`] : []
+	]);
+	if (!stdout.trim()) return [];
+	return stdout.trim().split("\n").map(parseLine);
+}
+function parseLine(line) {
+	const parts = line.split("|");
+	const hash = parts[0] ?? "";
+	const author = parts[1] ?? "";
+	const dateRaw = parts[2] ?? "";
+	const message = parts[3] ?? "";
+	return {
+		hash,
+		author,
+		date: dateRaw.slice(0, 10),
+		message,
+		type: extractType(message)
+	};
+}
+function extractType(message) {
+	return message.match(/^(\w+)(?:\(.+?\))?:/)?.[1] ?? "other";
+}
+
+//#endregion
+//#region src/core/template.ts
+function buildMissionSpec(commits, targetFile) {
+	const commitBlock = commits.map((c) => `- \`${c.hash}\` ${c.message} (${c.author}, ${c.date})`).join("\n");
+	return {
+		prompt: [
+			`You are a documentation update assistant. Update the changelog section in ${targetFile} based on the following git commits.`,
+			"",
+			"## Rules",
+			"1. Only modify content between `<!-- log-agent-start -->` and `<!-- log-agent-end -->` markers",
+			"2. Group commits by date, most recent first",
+			"3. Each commit should be a single bullet point with a type badge",
+			"4. Do not modify anything outside the markers",
+			"5. Write in the same language as the existing document",
+			"",
+			"## Commits",
+			commitBlock,
+			"",
+			"## Output format example",
+			"```markdown",
+			"### 2026-02-05",
+			"- **feat** Implement FilePreview component with transition effects (`8a2f3b4`)",
+			"- **fix** Adjust MobileMenu padding for better responsiveness (`4d1e9a2`)",
+			"```",
+			"",
+			`Directly edit ${targetFile}. Do not output any explanation.`
+		].join("\n"),
+		targetFile
+	};
+}
+
+//#endregion
+//#region src/core/bridge.ts
+async function executeMission(spec) {
+	try {
+		const { stdout } = await execa("claude", [
+			"-p",
+			"--allowedTools",
+			["Read", "Edit"].join(",")
+		], {
+			input: spec.prompt,
+			timeout: 6e4
+		});
+		return {
+			success: true,
+			output: stdout
+		};
+	} catch (error) {
+		const message = error instanceof Error ? error.message : "Unknown error occurred";
+		throw new Error(`claude -p execution failed: ${message}`);
+	}
+}
+
+//#endregion
+//#region src/core/marker.ts
+const START_TAG = "<!-- log-agent-start -->";
+const END_TAG = "<!-- log-agent-end -->";
+async function checkMarkers(filePath) {
+	try {
+		const content = await readFile(filePath, "utf-8");
+		const hasStart = content.includes(START_TAG);
+		const hasEnd = content.includes(END_TAG);
+		const lastDate = hasStart && hasEnd ? extractLastDate(content) : void 0;
+		return {
+			found: hasStart && hasEnd,
+			lastDate,
+			startTag: START_TAG,
+			endTag: END_TAG
+		};
+	} catch {
+		return {
+			found: false,
+			lastDate: void 0,
+			startTag: START_TAG,
+			endTag: END_TAG
+		};
+	}
+}
+function extractLastDate(content) {
+	const startIdx = content.indexOf(START_TAG);
+	const endIdx = content.indexOf(END_TAG);
+	if (startIdx === -1 || endIdx === -1) return void 0;
+	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/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;
+	try {
+		console.log(chalk.blue("Starting log-agent sync..."));
+		const markers = await checkMarkers(targetFile);
+		if (!dryRun && !markers.found) {
+			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;
+			return;
+		}
+		const effectiveSince = since ?? markers.lastDate;
+		if (effectiveSince) console.log(chalk.gray(`Fetching commits since ${effectiveSince}`));
+		const commits = await getCommits(effectiveSince);
+		if (commits.length === 0) {
+			console.log(chalk.yellow("No commits found, skipping sync."));
+			return;
+		}
+		console.log(chalk.gray(`Found ${commits.length} commit(s)`));
+		const spec = buildMissionSpec(commits, targetFile);
+		if (dryRun) {
+			console.log(chalk.yellow("--- Dry Run: Mission Spec ---"));
+			console.log(spec.prompt);
+			console.log(chalk.yellow("--- End ---"));
+			return;
+		}
+		console.log(chalk.gray("Mission spec generated, invoking claude -p..."));
+		const result = await executeMission(spec);
+		console.log(chalk.green("Sync completed successfully."));
+		console.log(chalk.gray(result.output));
+	} catch (error) {
+		const message = error instanceof Error ? error.message : "Unknown error";
+		if (message.includes("ENOENT") && message.includes("claude")) {
+			console.error(chalk.red("Claude Code is not installed."));
+			console.error(chalk.gray("Run: npm install -g @anthropic-ai/claude-code"));
+		} else if (message.includes("not a git repository")) console.error(chalk.red("Not a git repository."));
+		else console.error(chalk.red(`Sync failed: ${message}`));
+		process.exitCode = 1;
+	}
+});
+program.parse();
+
+//#endregion
+export {  };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "change-log-agent",
+  "version": "1.0.0",
+  "description": "AI-powered CLI that syncs git commit history to project documentation via Claude Code",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "bin": {
+    "log-agent": "dist/index.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "cli",
+    "git",
+    "changelog",
+    "documentation",
+    "claude",
+    "ai"
+  ],
+  "author": "Eric Cai",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ericcai0814/log-agent.git"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "execa": "^9.6.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}