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

package/README.md

@@ -96,6 +96,28 @@ npx @vibe-x/agent-better-checkpoint --platform cursor
 npx @vibe-x/agent-better-checkpoint --platform claude
 ```
 
+### Project-local Install
+
+Install scripts into your project for self-contained setup (commit with repo):
+
+```bash
+cd /path/to/your/project
+npx @vibe-x/agent-better-checkpoint --target .
+```
+
+Or specify a target directory:
+
+```bash
+npx @vibe-x/agent-better-checkpoint --target /path/to/your/project
+```
+
+Uninstall project-local only:
+
+```bash
+npx @vibe-x/agent-better-checkpoint --uninstall --target .
+npx @vibe-x/agent-better-checkpoint --uninstall --target /path/to/project
+```
+
 ### Via [skills.sh](https://skills.sh)
 
 ```bash

package/bin/cli.mjs

@@ -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>             Install to specified project directory (. for cwd)
   --uninstall                 Remove installed files and hook registrations
   -h, --help                  Show this help message
 `);
@@ -234,6 +243,37 @@ function registerCursorHook(osType) {
   console.log(`  Config  → ${hooksPath}`);
 }
 
+function installProjectLocal(targetDir, osType) {
+  const projectBase = join(resolve(targetDir), '.vibe-x', 'agent-better-checkpoint');
+  ensureDir(projectBase);
+
+  if (osType === 'unix') {
+    copyFileSafe(join(PLATFORM_DIR, 'unix', 'checkpoint.sh'), join(projectBase, 'checkpoint.sh'));
+    copyFileSafe(join(PLATFORM_DIR, 'unix', 'check_uncommitted.sh'), join(projectBase, 'check_uncommitted.sh'));
+    setExecutable(join(projectBase, 'checkpoint.sh'));
+    setExecutable(join(projectBase, 'check_uncommitted.sh'));
+  }
+  copyFileSafe(join(PLATFORM_DIR, 'win', 'checkpoint.ps1'), join(projectBase, 'checkpoint.ps1'));
+  copyFileSafe(join(PLATFORM_DIR, 'win', 'check_uncommitted.ps1'), join(projectBase, 'check_uncommitted.ps1'));
+
+  const configDest = join(projectBase, 'config.yml');
+  if (!existsSync(configDest) && existsSync(CONFIG_TEMPLATE)) {
+    copyFileSafe(CONFIG_TEMPLATE, configDest);
+  }
+
+  console.log(`  Project → ${projectBase}/`);
+}
+
+function uninstallProjectLocal(targetDir) {
+  const projectBase = join(resolve(targetDir), '.vibe-x', 'agent-better-checkpoint');
+  if (existsSync(projectBase)) {
+    rmSync(projectBase, { recursive: true, force: true });
+    console.log(`  Removed project-local: ${projectBase}`);
+  } else {
+    console.log(`  ${projectBase} not found, nothing to remove`);
+  }
+}
+
 function registerClaudeHook(osType) {
   const settingsPath = join(homedir(), '.claude', 'settings.json');
   let settings = readJsonFile(settingsPath) || {};
@@ -268,6 +308,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 +377,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 +388,72 @@ function main() {
   }
 
   if (args.uninstall) {
-    // Uninstall flow
-    console.log(`\n[${aiPlatform === 'cursor' ? 'Cursor' : 'Claude Code'}] Uninstalling...`);
+    if (projectTargetDir) {
+      console.log('\n[Project-local] Uninstalling...');
+      uninstallProjectLocal(projectTargetDir);
+    }
 
-    if (aiPlatform === 'cursor') {
-      uninstallCursorSkill();
-      unregisterCursorHook();
-    } else {
-      uninstallClaudeSkill();
-      unregisterClaudeHook();
+    // 指定 --platform 时只清该平台；未指定时清理所有已安装的平台
+    const platforms = args.platform
+      ? [args.platform]
+      : ['cursor', 'claude'].filter(p => hasInstallation(p));
+
+    if (!projectTargetDir || args.platform) {
+      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();
+      }
     }
 
-    uninstallScripts();
-    console.log(`\n✅ Uninstallation complete!`);
+    if (platforms.length === 0 && !projectTargetDir) {
+      console.log('\nNo installation found for any platform.');
+    }
+    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 AI platform for global hook. Specify --platform cursor|claude');
+        process.exit(1);
+      }
+      console.log(`\n[${aiPlatform === 'cursor' ? 'Cursor' : 'Claude Code'}] Installing... (OS: ${osType})`);
+      installScripts(osType);
+      installSkill(aiPlatform);
+      if (aiPlatform === 'cursor') {
+        registerCursorHook(osType);
+      } else {
+        registerClaudeHook(osType);
+      }
+      installProjectLocal(projectTargetDir, osType);
     } 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('\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! 🎉`);
+    if (projectTargetDir) {
+      const projectBase = join(resolve(projectTargetDir), '.vibe-x', 'agent-better-checkpoint');
+      console.log(`  📁 Project-local     → ${projectBase}/`);
+    }
+    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.0",
   "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.0"
   author: "alienzhou"
   category: "version-control"
 ---
@@ -26,10 +26,10 @@ Before your first commit, verify the checkpoint scripts are available:
 If neither exists, run:
 
 ```bash
-npx @vibe-x/agent-better-checkpoint@0.2.0
+npx @vibe-x/agent-better-checkpoint@0.3.0
 ```
 
-This installs the global scripts and stop hook. Projects can also commit `.vibe-x/agent-better-checkpoint/` (config + scripts) for self-contained setup.
+This installs the global scripts and stop hook. For self-contained setup (commit with project), add `--target .` or `--target <path>`.
 
 ---
 
@@ -177,4 +177,4 @@ This should feel natural — commit as you go, like any good developer.
 
 ---
 
-**Version**: 0.2.0
+**Version**: 0.3.0