@vibe-x/agent-better-checkpoint 0.2.0 → 0.3.1

package/README.md

@@ -96,6 +96,23 @@ npx @vibe-x/agent-better-checkpoint --platform cursor
 npx @vibe-x/agent-better-checkpoint --platform claude
 ```
 
+### Project-only Install
+
+Install only into your project (no global changes). Uses Cursor's project-level [skills](https://cursor.com/docs/context/skills) and [hooks](https://cursor.com/docs/agent/hooks):
+
+```bash
+cd /path/to/your/project
+npx @vibe-x/agent-better-checkpoint --platform cursor --target .
+```
+
+Creates: `.cursor/skills/`, `.cursor/hooks.json`, `.vibe-x/agent-better-checkpoint/`. Commit these with your repo.
+
+Uninstall project-only:
+
+```bash
+npx @vibe-x/agent-better-checkpoint --uninstall --target .
+```
+
 ### Via [skills.sh](https://skills.sh)
 
 ```bash
@@ -106,14 +123,23 @@ The AI agent will auto-bootstrap the runtime scripts on first use.
 
 ### What Gets Installed
 
+**Global** (no `--target`):
+
 | Location | Content |
 |----------|---------|
 | `~/.vibe-x/agent-better-checkpoint/scripts/` | Commit script (`checkpoint.sh` / `.ps1`) |
 | `~/.vibe-x/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 |
+| `~/.cursor/skills/` or `~/.claude/skills/` | `SKILL.md` — AI agent instructions |
+| `~/.cursor/hooks.json` or `~/.claude/settings.json` | Stop hook registration |
 
-> **Project-local mode**: Projects can also commit `.vibe-x/agent-better-checkpoint/` (config + scripts) for self-contained setup. When present, the global hook delegates to the project-local scripts automatically.
+**Project-only** (`--target .`):
+
+| Location | Content |
+|----------|---------|
+| `<project>/.cursor/skills/agent-better-checkpoint/` | `SKILL.md` |
+| `<project>/.cursor/hooks.json` | Stop hook (Cursor only) |
+| `<project>/.cursor/hooks/` | `check_uncommitted.sh` |
+| `<project>/.vibe-x/agent-better-checkpoint/` | `checkpoint.sh`, `config.yml` |
 
 ### Uninstall
 

package/bin/cli.mjs

@@ -12,7 +12,7 @@
  *   npx @vibe-x/agent-better-checkpoint --uninstall
  */
 
-import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, chmodSync, rmSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, chmodSync, rmSync, statSync, readdirSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { homedir, platform } from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -31,13 +31,14 @@ const SKILL_NAME = 'agent-better-checkpoint';
 // In-package source paths
 const PLATFORM_DIR = join(PKG_ROOT, 'platform');
 const SKILL_SRC = join(PKG_ROOT, 'skill', 'SKILL.md');
+const CONFIG_TEMPLATE = join(PLATFORM_DIR, 'config.template.yml');
 
 // ============================================================
 // Argument parsing
 // ============================================================
 
 function parseArgs(argv) {
-  const args = { platform: null, uninstall: false };
+  const args = { platform: null, uninstall: false, target: null };
   for (let i = 2; i < argv.length; i++) {
     switch (argv[i]) {
       case '--platform':
@@ -47,6 +48,13 @@ function parseArgs(argv) {
           process.exit(1);
         }
         break;
+      case '--target':
+        args.target = argv[++i];
+        if (!args.target) {
+          console.error('Error: --target requires a path argument');
+          process.exit(1);
+        }
+        break;
       case '--uninstall':
         args.uninstall = true;
         break;
@@ -73,6 +81,7 @@ Usage:
 
 Options:
   --platform <cursor|claude>  Target AI platform (auto-detected if omitted)
+  --target <path>             Project-only install (no global). Use . for cwd
   --uninstall                 Remove installed files and hook registrations
   -h, --help                  Show this help message
 `);
@@ -144,31 +153,17 @@ function installScripts(osType) {
   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(join(PLATFORM_DIR, 'unix', 'checkpoint.sh'), join(scriptsDir, 'checkpoint.sh'));
+  copyFileSafe(join(PLATFORM_DIR, 'unix', 'check_uncommitted.sh'), join(hooksDir, 'check_uncommitted.sh'));
+  setExecutable(join(scriptsDir, 'checkpoint.sh'));
+  setExecutable(join(hooksDir, 'check_uncommitted.sh'));
 
-    copyFileSafe(checkpointSrc, checkpointDest);
-    copyFileSafe(hookSrc, hookDest);
+  copyFileSafe(join(PLATFORM_DIR, 'win', 'checkpoint.ps1'), join(scriptsDir, 'checkpoint.ps1'));
+  copyFileSafe(join(PLATFORM_DIR, 'win', 'check_uncommitted.ps1'), join(hooksDir, 'check_uncommitted.ps1'));
 
-    console.log(`  Scripts → ${scriptsDir}\\checkpoint.ps1`);
-    console.log(`  Hooks   → ${hooksDir}\\check_uncommitted.ps1`);
-  }
+  console.log(`  Scripts → ${scriptsDir}/`);
+  console.log(`  Hooks   → ${hooksDir}/`);
 }
 
 function installSkill(aiPlatform) {
@@ -216,12 +211,6 @@ function registerCursorHook(osType) {
     hookCmd = `powershell -File "${INSTALL_BASE}\\hooks\\stop\\check_uncommitted.ps1"`;
   }
 
-  // Check if already registered
-  const alreadyRegistered = config.hooks.stop.some(
-    h => typeof h === 'object' && h.command && h.command.includes(SKILL_NAME.replace(/-/g, ''))
-  );
-
-  // More precise check: command includes agent-better-checkpoint
   const registered = config.hooks.stop.some(
     h => typeof h === 'object' && h.command && h.command.includes('agent-better-checkpoint')
   );
@@ -234,6 +223,111 @@ function registerCursorHook(osType) {
   console.log(`  Config  → ${hooksPath}`);
 }
 
+// 项目级安装：仅写入 target 目录，不触碰全局
+function installProjectOnly(targetDir, aiPlatform, osType) {
+  const root = resolve(targetDir);
+
+  // .vibe-x/agent-better-checkpoint: checkpoint 脚本 + config
+  const vibeXBase = join(root, '.vibe-x', 'agent-better-checkpoint');
+  ensureDir(vibeXBase);
+  copyFileSafe(join(PLATFORM_DIR, 'unix', 'checkpoint.sh'), join(vibeXBase, 'checkpoint.sh'));
+  copyFileSafe(join(PLATFORM_DIR, 'win', 'checkpoint.ps1'), join(vibeXBase, 'checkpoint.ps1'));
+  setExecutable(join(vibeXBase, 'checkpoint.sh'));
+  const configDest = join(vibeXBase, 'config.yml');
+  if (!existsSync(configDest) && existsSync(CONFIG_TEMPLATE)) {
+    copyFileSafe(CONFIG_TEMPLATE, configDest);
+  }
+  console.log(`  Config  → ${vibeXBase}/`);
+
+  // Skill: .cursor/skills/ 或 .claude/skills/
+  const skillRoot = aiPlatform === 'cursor' ? '.cursor' : '.claude';
+  const skillDir = join(root, skillRoot, 'skills', SKILL_NAME);
+  copyFileSafe(SKILL_SRC, join(skillDir, 'SKILL.md'));
+  console.log(`  Skill   → ${skillDir}/`);
+
+  if (aiPlatform === 'cursor') {
+    // Cursor 支持项目级 hooks: .cursor/hooks.json + .cursor/hooks/
+    const hooksDir = join(root, '.cursor', 'hooks');
+    ensureDir(hooksDir);
+    copyFileSafe(join(PLATFORM_DIR, 'unix', 'check_uncommitted.sh'), join(hooksDir, 'check_uncommitted.sh'));
+    setExecutable(join(hooksDir, 'check_uncommitted.sh'));
+    copyFileSafe(join(PLATFORM_DIR, 'win', 'check_uncommitted.ps1'), join(hooksDir, 'check_uncommitted.ps1'));
+    const hookCmd = osType === 'unix'
+      ? 'bash .cursor/hooks/check_uncommitted.sh'
+      : `powershell -File ".cursor\\hooks\\check_uncommitted.ps1"`;
+    const hooksPath = join(root, '.cursor', 'hooks.json');
+    let config = readJsonFile(hooksPath) || { version: 1, hooks: {} };
+    if (!config.hooks) config.hooks = {};
+    if (!config.hooks.stop) config.hooks.stop = [];
+    const registered = config.hooks.stop.some(
+      h => typeof h === 'object' && h.command && h.command.includes('check_uncommitted')
+    );
+    if (!registered) {
+      config.hooks.stop.push({ command: hookCmd });
+    }
+    writeJsonFile(hooksPath, config);
+    console.log(`  Hooks   → ${hooksPath}`);
+  } else {
+    // Claude Code: settings.json 为全局，无项目级 hooks，仅安装 skill 和脚本
+    console.log(`  Hooks   → (Claude stop hook is global-only, skipped for project install)`);
+  }
+}
+
+function uninstallProjectOnly(targetDir, aiPlatform) {
+  const root = resolve(targetDir);
+
+  const vibeXBase = join(root, '.vibe-x', 'agent-better-checkpoint');
+  const skillRoot = aiPlatform === 'cursor' ? '.cursor' : '.claude';
+  const skillDir = join(root, skillRoot, 'skills', SKILL_NAME);
+  if (existsSync(vibeXBase)) {
+    rmSync(vibeXBase, { recursive: true, force: true });
+    console.log(`  Removed ${vibeXBase}`);
+  }
+
+  if (existsSync(skillDir)) {
+    rmSync(skillDir, { recursive: true, force: true });
+    console.log(`  Removed ${skillDir}`);
+  }
+  // 移除空的 .cursor/skills 或 .claude/skills 父目录
+  const skillsParent = join(root, skillRoot, 'skills');
+  if (existsSync(skillsParent)) {
+    try {
+      if (readdirSync(skillsParent).length === 0) {
+        rmSync(skillsParent, { recursive: true, force: true });
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  if (aiPlatform === 'cursor') {
+    const hooksPath = join(root, '.cursor', 'hooks.json');
+    if (existsSync(hooksPath)) {
+      const config = readJsonFile(hooksPath);
+      if (config?.hooks?.stop) {
+        config.hooks.stop = config.hooks.stop.filter(
+          h => !(typeof h === 'object' && h.command && h.command.includes('check_uncommitted'))
+        );
+        if (config.hooks.stop.length === 0) delete config.hooks.stop;
+        if (Object.keys(config.hooks || {}).length === 0) {
+          rmSync(hooksPath, { force: true });
+        } else {
+          writeJsonFile(hooksPath, config);
+        }
+        console.log(`  Cleaned ${hooksPath}`);
+      }
+    }
+    const hooksDir = join(root, '.cursor', 'hooks');
+    const shPath = join(hooksDir, 'check_uncommitted.sh');
+    const ps1Path = join(hooksDir, 'check_uncommitted.ps1');
+    if (existsSync(shPath)) rmSync(shPath, { force: true });
+    if (existsSync(ps1Path)) rmSync(ps1Path, { force: true });
+    if (existsSync(hooksDir) && readdirSync(hooksDir).length === 0) {
+      rmSync(hooksDir, { recursive: true, force: true });
+    }
+  }
+}
+
 function registerClaudeHook(osType) {
   const settingsPath = join(homedir(), '.claude', 'settings.json');
   let settings = readJsonFile(settingsPath) || {};
@@ -268,6 +362,12 @@ function registerClaudeHook(osType) {
 // Uninstall logic
 // ============================================================
 
+function hasInstallation(platform) {
+  const home = homedir();
+  const skillDir = join(home, platform === 'cursor' ? '.cursor' : '.claude', 'skills', SKILL_NAME);
+  return existsSync(skillDir);
+}
+
 function uninstallScripts() {
   if (existsSync(INSTALL_BASE)) {
     rmSync(INSTALL_BASE, { recursive: true, force: true });
@@ -331,8 +431,9 @@ function main() {
   const args = parseArgs(process.argv);
   const osType = getOSType();
   const aiPlatform = args.platform || detectAIPlatform();
+  const projectTargetDir = args.target ? resolve(args.target) : null;
 
-  if (!aiPlatform) {
+  if (!aiPlatform && !projectTargetDir && !args.uninstall) {
     console.error(
       'Error: could not detect AI platform.\n' +
       'Please specify: npx @vibe-x/agent-better-checkpoint --platform cursor|claude'
@@ -341,38 +442,65 @@ function main() {
   }
 
   if (args.uninstall) {
-    // Uninstall flow
-    console.log(`\n[${aiPlatform === 'cursor' ? 'Cursor' : 'Claude Code'}] Uninstalling...`);
-
-    if (aiPlatform === 'cursor') {
-      uninstallCursorSkill();
-      unregisterCursorHook();
+    if (projectTargetDir) {
+      // 优先从项目目录检测平台（与安装时一致），否则用 --platform 或全局检测
+      let platform = args.platform;
+      if (!platform) {
+        const cursorSkill = join(projectTargetDir, '.cursor', 'skills', SKILL_NAME);
+        const claudeSkill = join(projectTargetDir, '.claude', 'skills', SKILL_NAME);
+        if (existsSync(cursorSkill)) platform = 'cursor';
+        else if (existsSync(claudeSkill)) platform = 'claude';
+      }
+      if (!platform) platform = aiPlatform;
+      if (!platform) {
+        console.error('Error: --target uninstall requires --platform cursor|claude (or project must have skill installed)');
+        process.exit(1);
+      }
+      console.log(`\n[Project-local] Uninstalling from ${projectTargetDir}...`);
+      uninstallProjectOnly(projectTargetDir, platform);
     } else {
-      uninstallClaudeSkill();
-      unregisterClaudeHook();
+      const platforms = args.platform
+        ? [args.platform]
+        : ['cursor', 'claude'].filter(p => hasInstallation(p));
+      for (const p of platforms) {
+        console.log(`\n[${p === 'cursor' ? 'Cursor' : 'Claude Code'}] Uninstalling...`);
+        if (p === 'cursor') {
+          uninstallCursorSkill();
+          unregisterCursorHook();
+        } else {
+          uninstallClaudeSkill();
+          unregisterClaudeHook();
+        }
+      }
+      if (platforms.length > 0) uninstallScripts();
+      if (platforms.length === 0) console.log('\nNo global installation found.');
     }
-
-    uninstallScripts();
-    console.log(`\n✅ Uninstallation complete!`);
+    console.log('\n✅ Uninstallation complete!');
   } else {
-    // Install flow
-    console.log(`\n[${aiPlatform === 'cursor' ? 'Cursor' : 'Claude Code'}] Installing... (OS: ${osType})`);
-
-    installScripts(osType);
-    installSkill(aiPlatform);
-
-    if (aiPlatform === 'cursor') {
-      registerCursorHook(osType);
+    if (projectTargetDir) {
+      if (!aiPlatform) {
+        console.error('Error: --target requires --platform cursor|claude');
+        process.exit(1);
+      }
+      console.log(`\n[Project-local] Installing to ${projectTargetDir}... (OS: ${osType})`);
+      installProjectOnly(projectTargetDir, aiPlatform, osType);
+      console.log('\n✅ Installation complete! (project-only, no global changes)');
     } else {
-      registerClaudeHook(osType);
+      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 → ~/.vibe-x/agent-better-checkpoint/scripts/ (.sh + .ps1)`);
+      console.log(`  🔒 Stop hook         → ~/.vibe-x/agent-better-checkpoint/hooks/stop/ (.sh + .ps1)`);
+      console.log(`  📖 SKILL.md          → ${aiPlatform === 'cursor' ? '~/.cursor/skills/' : '~/.claude/skills/'}${SKILL_NAME}/`);
     }
-
-    console.log(`\n✅ Installation complete!`);
-    console.log(`\nInstalled components:`);
-    console.log(`  📜 Checkpoint script → ~/.vibe-x/agent-better-checkpoint/scripts/`);
-    console.log(`  🔒 Stop hook         → ~/.vibe-x/agent-better-checkpoint/hooks/stop/`);
-    console.log(`  📖 SKILL.md          → ${aiPlatform === 'cursor' ? '~/.cursor/skills/' : '~/.claude/skills/'}${SKILL_NAME}/`);
-    console.log(`\nThe AI agent will now auto-commit with semantic messages. Happy coding! 🎉`);
+    console.log('\nThe AI agent will now auto-commit with semantic messages. Happy coding! 🎉');
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-x/agent-better-checkpoint",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Semantic Git checkpoint commits for AI coding sessions",
   "type": "module",
   "bin": {

package/platform/config.template.yml

@@ -0,0 +1,16 @@
+# Checkpoint commit trigger conditions
+#
+# Controls when stop hook (check_uncommitted) triggers commit reminder.
+# Affects only stop hook detection, not checkpoint.sh commit behavior.
+
+# Trigger reminder if ANY condition met (OR)
+# Empty/commented = condition disabled
+trigger_if_any:
+  # min_changed_files: 3   # At least N active files changed
+  min_changed_lines: 5      # At least N lines changed
+
+# Passive file patterns — matched files do not trigger reminder alone
+passive_patterns:
+  - ".discuss/**"
+  - ".vibe-x/**"
+  - ".DS_Store"

package/skill/SKILL.md

@@ -3,7 +3,7 @@ name: agent-better-checkpoint
 description: "Automatically creates semantic Git checkpoint commits during AI coding sessions. Replaces opaque platform checkpoints with transparent, queryable Git commits using Conventional Commits format with Git Trailers. You MUST follow this skill whenever you make code changes — commit after each meaningful edit."
 license: MIT
 metadata:
-  version: "0.2.0"
+  version: "0.3.1"
   author: "alienzhou"
   category: "version-control"
 ---
@@ -20,16 +20,18 @@ You are an AI coding assistant with **checkpoint awareness**. Every meaningful e
 
 Before your first commit, verify the checkpoint scripts are available:
 
-**Project-local (preferred, committed with project):** Check if `.vibe-x/agent-better-checkpoint/checkpoint.sh` exists in the workspace.
-**Global fallback:** Check if `~/.vibe-x/agent-better-checkpoint/scripts/checkpoint.sh` exists (macOS/Linux) or `$env:USERPROFILE/.vibe-x/agent-better-checkpoint/scripts/checkpoint.ps1` (Windows).
+**Project-local (preferred):** Check if `.vibe-x/agent-better-checkpoint/checkpoint.sh` (or `.ps1`) exists in the workspace.
+**Global fallback:** Check if `~/.vibe-x/agent-better-checkpoint/scripts/checkpoint.sh` (or `.ps1`) exists.
+
+Both `.sh` and `.ps1` are always installed regardless of current OS.
 
 If neither exists, run:
 
 ```bash
-npx @vibe-x/agent-better-checkpoint@0.2.0
+npx @vibe-x/agent-better-checkpoint@0.3.1
 ```
 
-This installs the global scripts and stop hook. Projects can also commit `.vibe-x/agent-better-checkpoint/` (config + scripts) for self-contained setup.
+Without `--target`: installs globally. With `--target .`: project-only (skill + hooks in `.cursor/`, scripts in `.vibe-x/`), no global changes.
 
 ---
 
@@ -94,29 +96,14 @@ Switch to flex-column layout with collapsible sidebar.
 
 ## 🛠️ How to Commit
 
-Call the checkpoint script after composing your message. Determine the OS and use the appropriate command.
-
-**Prefer project-local when present** (`.vibe-x/agent-better-checkpoint/` committed with project):
-
-**macOS/Linux:**
-
-```bash
-# Project-local (if .vibe-x/agent-better-checkpoint/ exists)
-.vibe-x/agent-better-checkpoint/checkpoint.sh "<commit-message>" "<user-prompt>"
-
-# Or global fallback
-~/.vibe-x/agent-better-checkpoint/scripts/checkpoint.sh "<commit-message>" "<user-prompt>"
-```
+Call the checkpoint script after composing your message. Both `.sh` and `.ps1` are always available — pick the one matching the current OS.
 
-**Windows (PowerShell):**
+**Prefer project-local when present**, fall back to global:
 
-```powershell
-# Project-local (if .vibe-x/agent-better-checkpoint/ exists)
-powershell -File ".\.vibe-x\agent-better-checkpoint\checkpoint.ps1" "<commit-message>" "<user-prompt>"
-
-# Or global fallback
-powershell -File "$env:USERPROFILE/.vibe-x/agent-better-checkpoint/scripts/checkpoint.ps1" "<commit-message>" "<user-prompt>"
-```
+| OS | Project-local | Global fallback |
+|----|--------------|-----------------|
+| macOS/Linux | `.vibe-x/agent-better-checkpoint/checkpoint.sh` | `~/.vibe-x/agent-better-checkpoint/scripts/checkpoint.sh` |
+| Windows | `powershell -File ".vibe-x\agent-better-checkpoint\checkpoint.ps1"` | `powershell -File "$env:USERPROFILE\.vibe-x\agent-better-checkpoint\scripts\checkpoint.ps1"` |
 
 ### Parameters:
 
@@ -129,7 +116,7 @@ powershell -File "$env:USERPROFILE/.vibe-x/agent-better-checkpoint/scripts/check
 ### Example (macOS/Linux):
 
 ```bash
-~/.vibe-x/agent-better-checkpoint/scripts/checkpoint.sh \
+.vibe-x/agent-better-checkpoint/checkpoint.sh \
   "checkpoint(auth): add JWT token refresh logic
 
 Implement automatic token refresh when access token expires.
@@ -140,7 +127,7 @@ Uses refresh token rotation for security." \
 ### Example (Windows):
 
 ```powershell
-powershell -File "$env:USERPROFILE/.vibe-x/agent-better-checkpoint/scripts/checkpoint.ps1" `
+powershell -File ".vibe-x\agent-better-checkpoint\checkpoint.ps1" `
   "checkpoint(auth): add JWT token refresh logic`n`nImplement automatic token refresh when access token expires.`nUses refresh token rotation for security." `
   "帮我实现 token 刷新机制"
 ```
@@ -177,4 +164,4 @@ This should feel natural — commit as you go, like any good developer.
 
 ---
 
-**Version**: 0.2.0
+**Version**: 0.3.1