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

package/README.md

@@ -96,26 +96,21 @@ npx @vibe-x/agent-better-checkpoint --platform cursor
 npx @vibe-x/agent-better-checkpoint --platform claude
 ```
 
-### Project-local Install
+### Project-only Install
 
-Install scripts into your project for self-contained setup (commit with repo):
+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 --target .
+npx @vibe-x/agent-better-checkpoint --platform cursor --target .
 ```
 
-Or specify a target directory:
+Creates: `.cursor/skills/`, `.cursor/hooks.json`, `.vibe-x/agent-better-checkpoint/`. Commit these with your repo.
 
-```bash
-npx @vibe-x/agent-better-checkpoint --target /path/to/your/project
-```
-
-Uninstall project-local only:
+Uninstall project-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)
@@ -128,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';
@@ -81,7 +81,7 @@ Usage:
 
 Options:
   --platform <cursor|claude>  Target AI platform (auto-detected if omitted)
-  --target <path>             Install to specified project directory (. for cwd)
+  --target <path>             Project-only install (no global). Use . for cwd
   --uninstall                 Remove installed files and hook registrations
   -h, --help                  Show this help message
 `);
@@ -153,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) {
@@ -225,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')
   );
@@ -243,34 +223,108 @@ 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');
+// 项目级安装：仅写入 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}/`);
 
-  console.log(`  Project → ${projectBase}/`);
-}
+  // 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}/`);
 
-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}`);
+  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 {
-    console.log(`  ${projectBase} not found, nothing to remove`);
+    // 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 });
+    }
   }
 }
 
@@ -389,16 +443,25 @@ function main() {
 
   if (args.uninstall) {
     if (projectTargetDir) {
-      console.log('\n[Project-local] Uninstalling...');
-      uninstallProjectLocal(projectTargetDir);
-    }
-
-    // 指定 --platform 时只清该平台；未指定时清理所有已安装的平台
-    const platforms = args.platform
-      ? [args.platform]
-      : ['cursor', 'claude'].filter(p => hasInstallation(p));
-
-    if (!projectTargetDir || args.platform) {
+      // 优先从项目目录检测平台（与安装时一致），否则用 --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 {
+      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') {
@@ -409,30 +472,19 @@ function main() {
           unregisterClaudeHook();
         }
       }
-      if (platforms.length > 0) {
-        uninstallScripts();
-      }
-    }
-
-    if (platforms.length === 0 && !projectTargetDir) {
-      console.log('\nNo installation found for any platform.');
+      if (platforms.length > 0) uninstallScripts();
+      if (platforms.length === 0) console.log('\nNo global installation found.');
     }
     console.log('\n✅ Uninstallation complete!');
   } else {
-if (projectTargetDir) {
-        if (!aiPlatform) {
-        console.error('Error: --target requires AI platform for global hook. Specify --platform cursor|claude');
+    if (projectTargetDir) {
+      if (!aiPlatform) {
+        console.error('Error: --target requires --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);
+      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 {
       console.log(`\n[${aiPlatform === 'cursor' ? 'Cursor' : 'Claude Code'}] Installing... (OS: ${osType})`);
       installScripts(osType);
@@ -442,16 +494,11 @@ if (projectTargetDir) {
       } else {
         registerClaudeHook(osType);
       }
-    }
-
-    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}/`);
-    if (projectTargetDir) {
-      const projectBase = join(resolve(projectTargetDir), '.vibe-x', 'agent-better-checkpoint');
-      console.log(`  📁 Project-local     → ${projectBase}/`);
+      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('\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.3.0",
+  "version": "0.3.2",
   "description": "Semantic Git checkpoint commits for AI coding sessions",
   "type": "module",
   "bin": {

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.3.0"
+  version: "0.3.2"
   author: "alienzhou"
   category: "version-control"
 ---
@@ -18,18 +18,23 @@ You are an AI coding assistant with **checkpoint awareness**. Every meaningful e
 
 ## 🔧 Installation Check
 
-Before your first commit, verify the checkpoint scripts are available:
+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).
+**IMPORTANT: Use your file-listing/read tools (NOT shell `test -f`) to check existence.** Shell relative paths break when CWD ≠ workspace root.
+
+Check in order (stop at first hit):
+1. **Project-local (preferred):** `.vibe-x/agent-better-checkpoint/checkpoint.sh` (or `.ps1`) relative to workspace root.
+2. **Global fallback:** `~/.vibe-x/agent-better-checkpoint/scripts/checkpoint.sh` (or `.ps1`).
+
+Both `.sh` and `.ps1` are always installed regardless of current OS.
 
 If neither exists, run:
 
 ```bash
-npx @vibe-x/agent-better-checkpoint@0.3.0
+npx @vibe-x/agent-better-checkpoint@0.3.2
 ```
 
-This installs the global scripts and stop hook. For self-contained setup (commit with project), add `--target .` or `--target <path>`.
+Without `--target`: installs globally. With `--target .`: project-only (skill + hooks in `.cursor/`, scripts in `.vibe-x/`), no global changes.
 
 ---
 
@@ -94,29 +99,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):
+Call the checkpoint script after composing your message. Both `.sh` and `.ps1` are always available — pick the one matching the current OS.
 
-**macOS/Linux:**
+**Prefer project-local when present**, fall back to global:
 
-```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>"
-```
-
-**Windows (PowerShell):**
-
-```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 +119,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 +130,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 +167,4 @@ This should feel natural — commit as you go, like any good developer.
 
 ---
 
-**Version**: 0.3.0
+**Version**: 0.3.2