@vibe-x/agent-better-checkpoint 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alien ZHOU
+
+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,124 @@
+# Agent Better Checkpoint
+
+**One-line install, zero config.** Turns AI agent edits into transparent, queryable Git commits.
+
+```bash
+npx @vibe-x/agent-better-checkpoint
+```
+
+That's it. Your AI coding assistant (Cursor, Claude Code) will now auto-commit every meaningful edit with semantic messages and structured metadata — no more opaque checkpoints.
+
+---
+
+## The Problem
+
+AI coding assistants create "checkpoints" as you work, but these are black-box snapshots:
+- **Unreadable** — no meaningful commit messages
+- **Unnavigable** — can't browse or diff individual changes
+- **Unqueryable** — no way to filter, search, or trace back
+
+## The Solution
+
+Agent Better Checkpoint replaces them with real Git commits:
+
+```
+checkpoint(api): add user registration endpoint
+
+Implement POST /api/users with email/password validation.
+Includes bcrypt hashing and duplicate email check.
+
+Agent: cursor
+Checkpoint-Type: auto
+User-Prompt: 帮我实现用户注册接口，需要邮...要密码加密
+```
+
+Each commit follows [Conventional Commits](https://www.conventionalcommits.org/) and carries structured metadata via [Git Trailers](https://git-scm.com/docs/git-interpret-trailers) — queryable with standard Git tools:
+
+```bash
+git log --grep="^checkpoint("                          # all checkpoints
+git log --format="%(trailers:key=Agent,valueonly)"     # by agent
+git log --grep="User-Prompt:.*registration"            # by prompt keyword
+```
+
+---
+
+## How It Works
+
+Three components, fully automatic after install:
+
+| Component | What it does |
+|-----------|-------------|
+| **SKILL.md** | Instructs the AI to commit after each meaningful edit, with proper format |
+| **Commit Script** | Appends Git Trailers (agent, type, user prompt) and runs `git commit` |
+| **Stop Hook** | Safety net — reminds the AI to commit if anything is left uncommitted |
+
+```
+User gives task → AI edits code → AI calls checkpoint script → Git commit with trailers
+                                                              ↗
+                              Conversation ends → Stop hook checks for uncommitted changes
+```
+
+---
+
+## Installation
+
+### Prerequisites
+
+- Git ≥ 2.0
+- Node.js ≥ 18 (only needed for installation)
+- [Cursor](https://cursor.com) or [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+
+### Quick Install
+
+```bash
+npx @vibe-x/agent-better-checkpoint
+```
+
+Auto-detects your OS and AI platform. Or specify explicitly:
+
+```bash
+npx @vibe-x/agent-better-checkpoint --platform cursor
+npx @vibe-x/agent-better-checkpoint --platform claude
+```
+
+### Via [skills.sh](https://skills.sh)
+
+```bash
+npx skills add alienzhou/agent-better-checkpoint
+```
+
+The AI agent will auto-bootstrap the runtime scripts on first use.
+
+### What Gets Installed
+
+| Location | Content |
+|----------|---------|
+| `~/.agent-better-checkpoint/scripts/` | Commit script (`checkpoint.sh` / `.ps1`) |
+| `~/.agent-better-checkpoint/hooks/stop/` | Stop hook (`check_uncommitted.sh` / `.ps1`) |
+| Platform skill directory | `SKILL.md` — AI agent instructions |
+| Platform hook config | Stop hook registration |
+
+### Uninstall
+
+```bash
+npx @vibe-x/agent-better-checkpoint --uninstall
+```
+
+---
+
+## Platform Support
+
+| Platform | OS | Status |
+|----------|----|--------|
+| Cursor | macOS, Linux, Windows | ✅ |
+| Claude Code | macOS, Linux, Windows | ✅ |
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and publishing instructions.
+
+## License
+
+[MIT](LICENSE)

package/bin/cli.mjs

@@ -0,0 +1,380 @@
+#!/usr/bin/env node
+
+/**
+ * agent-better-checkpoint 安装器 (Node.js)
+ *
+ * 通过 npx 一键安装 checkpoint 脚本、stop hook 和 SKILL.md 到用户环境。
+ * 按平台（macOS/Linux vs Windows）选择性部署对应脚本。
+ *
+ * Usage:
+ *   npx @vibe-x/agent-better-checkpoint
+ *   npx @vibe-x/agent-better-checkpoint --platform cursor
+ *   npx @vibe-x/agent-better-checkpoint --uninstall
+ */
+
+import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, chmodSync, rmSync, statSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { homedir, platform } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+// ============================================================
+// 路径常量
+// ============================================================
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PKG_ROOT = resolve(__dirname, '..');
+
+const INSTALL_BASE = join(homedir(), '.agent-better-checkpoint');
+const SKILL_NAME = 'agent-better-checkpoint';
+
+// 包内源文件路径
+const PLATFORM_DIR = join(PKG_ROOT, 'platform');
+const SKILL_SRC = join(PKG_ROOT, 'skill', 'SKILL.md');
+
+// ============================================================
+// 参数解析
+// ============================================================
+
+function parseArgs(argv) {
+  const args = { platform: null, uninstall: false };
+  for (let i = 2; i < argv.length; i++) {
+    switch (argv[i]) {
+      case '--platform':
+        args.platform = argv[++i];
+        if (!['cursor', 'claude'].includes(args.platform)) {
+          console.error(`Error: unsupported platform "${args.platform}". Use "cursor" or "claude".`);
+          process.exit(1);
+        }
+        break;
+      case '--uninstall':
+        args.uninstall = true;
+        break;
+      case '--help':
+      case '-h':
+        printHelp();
+        process.exit(0);
+        break;
+      default:
+        console.error(`Unknown option: ${argv[i]}`);
+        printHelp();
+        process.exit(1);
+    }
+  }
+  return args;
+}
+
+function printHelp() {
+  console.log(`
+agent-better-checkpoint — Semantic Git Checkpoint Installer
+
+Usage:
+  npx @vibe-x/agent-better-checkpoint [options]
+
+Options:
+  --platform <cursor|claude>  Target AI platform (auto-detected if omitted)
+  --uninstall                 Remove installed files and hook registrations
+  -h, --help                  Show this help message
+`);
+}
+
+// ============================================================
+// 平台检测
+// ============================================================
+
+function detectAIPlatform() {
+  const home = homedir();
+  // 优先 Claude（如果两者都存在，用户可以用 --platform 覆盖）
+  if (existsSync(join(home, '.claude'))) return 'claude';
+  if (existsSync(join(home, '.cursor'))) return 'cursor';
+  return null;
+}
+
+function getOSType() {
+  const p = platform();
+  if (p === 'win32') return 'win';
+  return 'unix'; // darwin, linux, freebsd, etc.
+}
+
+// ============================================================
+// 文件操作辅助
+// ============================================================
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+function copyFileSafe(src, dest) {
+  ensureDir(dirname(dest));
+  copyFileSync(src, dest);
+}
+
+function setExecutable(filepath) {
+  try {
+    const st = statSync(filepath);
+    chmodSync(filepath, st.mode | 0o111);
+  } catch {
+    // Windows 下 chmod 可能无效，忽略
+  }
+}
+
+function readJsonFile(filepath) {
+  try {
+    return JSON.parse(readFileSync(filepath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeJsonFile(filepath, data) {
+  ensureDir(dirname(filepath));
+  writeFileSync(filepath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}
+
+// ============================================================
+// 安装逻辑
+// ============================================================
+
+function installScripts(osType) {
+  const scriptsDir = join(INSTALL_BASE, 'scripts');
+  const hooksDir = join(INSTALL_BASE, 'hooks', 'stop');
+
+  ensureDir(scriptsDir);
+  ensureDir(hooksDir);
+
+  if (osType === 'unix') {
+    const checkpointSrc = join(PLATFORM_DIR, 'unix', 'checkpoint.sh');
+    const hookSrc = join(PLATFORM_DIR, 'unix', 'check_uncommitted.sh');
+    const checkpointDest = join(scriptsDir, 'checkpoint.sh');
+    const hookDest = join(hooksDir, 'check_uncommitted.sh');
+
+    copyFileSafe(checkpointSrc, checkpointDest);
+    copyFileSafe(hookSrc, hookDest);
+    setExecutable(checkpointDest);
+    setExecutable(hookDest);
+
+    console.log(`  Scripts → ${scriptsDir}/checkpoint.sh`);
+    console.log(`  Hooks   → ${hooksDir}/check_uncommitted.sh`);
+  } else {
+    const checkpointSrc = join(PLATFORM_DIR, 'win', 'checkpoint.ps1');
+    const hookSrc = join(PLATFORM_DIR, 'win', 'check_uncommitted.ps1');
+    const checkpointDest = join(scriptsDir, 'checkpoint.ps1');
+    const hookDest = join(hooksDir, 'check_uncommitted.ps1');
+
+    copyFileSafe(checkpointSrc, checkpointDest);
+    copyFileSafe(hookSrc, hookDest);
+
+    console.log(`  Scripts → ${scriptsDir}\\checkpoint.ps1`);
+    console.log(`  Hooks   → ${hooksDir}\\check_uncommitted.ps1`);
+  }
+}
+
+function installSkill(aiPlatform) {
+  let skillDir;
+  let skillDest;
+
+  if (aiPlatform === 'cursor') {
+    // 检查 skills.sh 安装路径
+    const skillsShPath = join(homedir(), '.cursor', 'skills', SKILL_NAME, 'SKILL.md');
+    if (existsSync(skillsShPath)) {
+      console.log(`  Skill   → already installed at ${skillsShPath} (skipped)`);
+      return;
+    }
+
+    skillDir = join(homedir(), '.cursor', 'skills', SKILL_NAME);
+    skillDest = join(skillDir, 'SKILL.md');
+  } else if (aiPlatform === 'claude') {
+    // Claude Code: 作为 slash command 安装
+    const commandsDir = join(homedir(), '.claude', 'commands');
+    skillDest = join(commandsDir, `${SKILL_NAME}.md`);
+
+    if (existsSync(skillDest)) {
+      console.log(`  Skill   → already installed at ${skillDest} (skipped)`);
+      return;
+    }
+
+    skillDir = commandsDir;
+  }
+
+  copyFileSafe(SKILL_SRC, skillDest);
+  console.log(`  Skill   → ${skillDest}`);
+}
+
+function registerCursorHook(osType) {
+  const hooksPath = join(homedir(), '.cursor', 'hooks.json');
+  let config = readJsonFile(hooksPath) || { version: 1, hooks: {} };
+
+  if (!config.hooks) config.hooks = {};
+  if (!config.hooks.stop) config.hooks.stop = [];
+
+  // 构建 hook 命令
+  let hookCmd;
+  if (osType === 'unix') {
+    hookCmd = `bash ${INSTALL_BASE}/hooks/stop/check_uncommitted.sh`;
+  } else {
+    hookCmd = `powershell -File "${INSTALL_BASE}\\hooks\\stop\\check_uncommitted.ps1"`;
+  }
+
+  // 检查是否已注册
+  const alreadyRegistered = config.hooks.stop.some(
+    h => typeof h === 'object' && h.command && h.command.includes(SKILL_NAME.replace(/-/g, ''))
+  );
+
+  // 用更精确的检测：检查命令中是否包含 agent-better-checkpoint
+  const registered = config.hooks.stop.some(
+    h => typeof h === 'object' && h.command && h.command.includes('agent-better-checkpoint')
+  );
+
+  if (!registered) {
+    config.hooks.stop.push({ command: hookCmd });
+  }
+
+  writeJsonFile(hooksPath, config);
+  console.log(`  Config  → ${hooksPath}`);
+}
+
+function registerClaudeHook(osType) {
+  const settingsPath = join(homedir(), '.claude', 'settings.json');
+  let settings = readJsonFile(settingsPath) || {};
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.Stop) settings.hooks.Stop = [];
+
+  let hookCmd;
+  if (osType === 'unix') {
+    hookCmd = `bash ${INSTALL_BASE}/hooks/stop/check_uncommitted.sh`;
+  } else {
+    hookCmd = `powershell -File "${INSTALL_BASE}\\hooks\\stop\\check_uncommitted.ps1"`;
+  }
+
+  const registered = settings.hooks.Stop.some(
+    h => typeof h === 'object' &&
+         JSON.stringify(h).includes('agent-better-checkpoint')
+  );
+
+  if (!registered) {
+    settings.hooks.Stop.push({
+      matcher: '',
+      hooks: [{ type: 'command', command: hookCmd }]
+    });
+  }
+
+  writeJsonFile(settingsPath, settings);
+  console.log(`  Config  → ${settingsPath}`);
+}
+
+// ============================================================
+// 卸载逻辑
+// ============================================================
+
+function uninstallScripts() {
+  if (existsSync(INSTALL_BASE)) {
+    rmSync(INSTALL_BASE, { recursive: true, force: true });
+    console.log(`  Removed ${INSTALL_BASE}`);
+  } else {
+    console.log(`  ${INSTALL_BASE} not found, nothing to remove`);
+  }
+}
+
+function uninstallCursorSkill() {
+  const skillDir = join(homedir(), '.cursor', 'skills', SKILL_NAME);
+  if (existsSync(skillDir)) {
+    rmSync(skillDir, { recursive: true, force: true });
+    console.log(`  Removed skill: ${skillDir}`);
+  }
+}
+
+function uninstallClaudeSkill() {
+  const cmdFile = join(homedir(), '.claude', 'commands', `${SKILL_NAME}.md`);
+  if (existsSync(cmdFile)) {
+    rmSync(cmdFile, { force: true });
+    console.log(`  Removed command: ${cmdFile}`);
+  }
+}
+
+function unregisterCursorHook() {
+  const hooksPath = join(homedir(), '.cursor', 'hooks.json');
+  if (!existsSync(hooksPath)) return;
+
+  const config = readJsonFile(hooksPath);
+  if (!config || !config.hooks || !config.hooks.stop) return;
+
+  config.hooks.stop = config.hooks.stop.filter(
+    h => !(typeof h === 'object' && h.command && h.command.includes('agent-better-checkpoint'))
+  );
+
+  writeJsonFile(hooksPath, config);
+  console.log(`  Cleaned config: ${hooksPath}`);
+}
+
+function unregisterClaudeHook() {
+  const settingsPath = join(homedir(), '.claude', 'settings.json');
+  if (!existsSync(settingsPath)) return;
+
+  const settings = readJsonFile(settingsPath);
+  if (!settings || !settings.hooks || !settings.hooks.Stop) return;
+
+  settings.hooks.Stop = settings.hooks.Stop.filter(
+    h => !JSON.stringify(h).includes('agent-better-checkpoint')
+  );
+
+  writeJsonFile(settingsPath, settings);
+  console.log(`  Cleaned config: ${settingsPath}`);
+}
+
+// ============================================================
+// 主入口
+// ============================================================
+
+function main() {
+  const args = parseArgs(process.argv);
+  const osType = getOSType();
+  const aiPlatform = args.platform || detectAIPlatform();
+
+  if (!aiPlatform) {
+    console.error(
+      'Error: could not detect AI platform.\n' +
+      'Please specify: npx @vibe-x/agent-better-checkpoint --platform cursor|claude'
+    );
+    process.exit(1);
+  }
+
+  if (args.uninstall) {
+    // 卸载流程
+    console.log(`\n[${aiPlatform === 'cursor' ? 'Cursor' : 'Claude Code'}] Uninstalling...`);
+
+    if (aiPlatform === 'cursor') {
+      uninstallCursorSkill();
+      unregisterCursorHook();
+    } else {
+      uninstallClaudeSkill();
+      unregisterClaudeHook();
+    }
+
+    uninstallScripts();
+    console.log(`\n✅ Uninstallation complete!`);
+  } else {
+    // 安装流程
+    console.log(`\n[${aiPlatform === 'cursor' ? 'Cursor' : 'Claude Code'}] Installing... (OS: ${osType})`);
+
+    installScripts(osType);
+    installSkill(aiPlatform);
+
+    if (aiPlatform === 'cursor') {
+      registerCursorHook(osType);
+    } else {
+      registerClaudeHook(osType);
+    }
+
+    console.log(`\n✅ Installation complete!`);
+    console.log(`\nInstalled components:`);
+    console.log(`  📜 Checkpoint script → ~/.agent-better-checkpoint/scripts/`);
+    console.log(`  🔒 Stop hook         → ~/.agent-better-checkpoint/hooks/stop/`);
+    console.log(`  📖 SKILL.md          → ${aiPlatform === 'cursor' ? '~/.cursor/skills/' : '~/.claude/commands/'}${SKILL_NAME}/`);
+    console.log(`\nThe AI agent will now auto-commit with semantic messages. Happy coding! 🎉`);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@vibe-x/agent-better-checkpoint",
+  "version": "0.1.0",
+  "description": "Semantic Git checkpoint commits for AI coding sessions",
+  "type": "module",
+  "bin": {
+    "agent-better-checkpoint": "./bin/cli.mjs"
+  },
+  "files": [
+    "bin/",
+    "platform/",
+    "skill/",
+    "LICENSE"
+  ],
+  "keywords": [
+    "ai",
+    "agent",
+    "git",
+    "checkpoint",
+    "cursor",
+    "claude",
+    "conventional-commits",
+    "skills-sh"
+  ],
+  "license": "MIT",
+  "author": "alienzhou",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alienzhou/agent-better-checkpoint.git"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}