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

package/bin/cli.mjs

@@ -142,6 +142,80 @@ function writeJsonFile(filepath, data) {
   writeFileSync(filepath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
 }
 
+// ============================================================
+// AGENTS.md block management
+// ============================================================
+
+const AGENTS_BLOCK_START = '<!-- [ABC:agent-better-checkpoint:start] -->';
+const AGENTS_BLOCK_END = '<!-- [ABC:agent-better-checkpoint:end] -->';
+
+const AGENTS_BLOCK_CONTENT = `${AGENTS_BLOCK_START}
+## Checkpoint Commit Rule
+
+After completing any file edit (write_to_file, replace_in_file, multi_replace_in_file, or similar),
+you MUST:
+
+1. Load the "agent-better-checkpoint" skill (if not already loaded)
+2. Follow its instructions to create a checkpoint commit
+3. Do NOT proceed to the next task until the commit is done
+
+This ensures every meaningful code change is tracked with a semantic Git commit.
+${AGENTS_BLOCK_END}`;
+
+function injectAgentsMdBlock(targetDir) {
+  const agentsMdPath = join(targetDir, 'AGENTS.md');
+  let content = '';
+  
+  if (existsSync(agentsMdPath)) {
+    content = readFileSync(agentsMdPath, 'utf-8');
+    // Check if block already exists
+    if (content.includes(AGENTS_BLOCK_START)) {
+      console.log(`  AGENTS.md → block already exists (skipped)`);
+      return;
+    }
+  }
+  
+  // Append block to end of file (or create new file)
+  const newContent = content
+    ? content.trimEnd() + '\n\n' + AGENTS_BLOCK_CONTENT + '\n'
+    : AGENTS_BLOCK_CONTENT + '\n';
+  
+  writeFileSync(agentsMdPath, newContent, 'utf-8');
+  console.log(`  AGENTS.md → ${agentsMdPath}`);
+}
+
+function removeAgentsMdBlock(targetDir) {
+  const agentsMdPath = join(targetDir, 'AGENTS.md');
+  
+  if (!existsSync(agentsMdPath)) {
+    return;
+  }
+  
+  const content = readFileSync(agentsMdPath, 'utf-8');
+  
+  if (!content.includes(AGENTS_BLOCK_START)) {
+    return;
+  }
+  
+  // Remove the block (including surrounding newlines)
+  const blockRegex = new RegExp(
+    `\\n*${AGENTS_BLOCK_START.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\s\\S]*?${AGENTS_BLOCK_END.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\n*`,
+    'g'
+  );
+  
+  let newContent = content.replace(blockRegex, '\n');
+  newContent = newContent.trim();
+  
+  if (newContent === '') {
+    // If file is empty after removal, delete it
+    rmSync(agentsMdPath, { force: true });
+    console.log(`  Removed ${agentsMdPath} (empty after cleanup)`);
+  } else {
+    writeFileSync(agentsMdPath, newContent + '\n', 'utf-8');
+    console.log(`  Cleaned ${agentsMdPath}`);
+  }
+}
+
 // ============================================================
 // Install logic
 // ============================================================
@@ -271,6 +345,9 @@ function installProjectOnly(targetDir, aiPlatform, osType) {
     // Claude Code: settings.json 为全局，无项目级 hooks，仅安装 skill 和脚本
     console.log(`  Hooks   → (Claude stop hook is global-only, skipped for project install)`);
   }
+
+  // Inject AGENTS.md block (project-only)
+  injectAgentsMdBlock(root);
 }
 
 function uninstallProjectOnly(targetDir, aiPlatform) {
@@ -326,6 +403,9 @@ function uninstallProjectOnly(targetDir, aiPlatform) {
       rmSync(hooksDir, { recursive: true, force: true });
     }
   }
+
+  // Remove AGENTS.md block
+  removeAgentsMdBlock(root);
 }
 
 function registerClaudeHook(osType) {

package/package.json

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

package/platform/unix/checkpoint.sh

@@ -42,10 +42,11 @@ fi
 # Platform detection
 # ============================================================
 detect_platform() {
-    if [[ -n "${CLAUDE_CODE:-}" ]] || command -v claude &>/dev/null; then
-        echo "claude-code"
-    elif [[ -n "${CURSOR_VERSION:-}" ]] || [[ -n "${CURSOR_TRACE_ID:-}" ]]; then
+    # 优先检测运行时环境变量（谁在调用），而非安装态（command -v）
+    if [[ -n "${CURSOR_AGENT:-}" ]] || [[ -n "${CURSOR_TRACE_ID:-}" ]] || [[ -n "${CURSOR_VERSION:-}" ]]; then
         echo "cursor"
+    elif [[ -n "${CLAUDE_CODE:-}" ]]; then
+        echo "claude-code"
     else
         echo "unknown"
     fi

package/platform/win/checkpoint.ps1

@@ -38,12 +38,13 @@ $ErrorActionPreference = "Stop"
 # ============================================================
 
 function Detect-Platform {
-    if ($env:CLAUDE_CODE -or (Get-Command claude -ErrorAction SilentlyContinue)) {
-        return "claude-code"
-    }
-    if ($env:CURSOR_VERSION -or $env:CURSOR_TRACE_ID) {
+    # 优先检测运行时环境变量（谁在调用），而非安装态（Get-Command）
+    if ($env:CURSOR_AGENT -or $env:CURSOR_TRACE_ID -or $env:CURSOR_VERSION) {
         return "cursor"
     }
+    if ($env:CLAUDE_CODE) {
+        return "claude-code"
+    }
     return "unknown"
 }
 

package/skill/SKILL.md

@@ -1,9 +1,9 @@
 ---
 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."
+description: "Creates semantic Git checkpoint commits during AI coding sessions with Conventional Commits format and Git Trailers. Use after completing code edits, or when user says 'commit changes', 'create checkpoint', or 'save my progress'."
 license: MIT
 metadata:
-  version: "0.3.1"
+  version: "0.3.3"
   author: "alienzhou"
   category: "version-control"
 ---
@@ -18,17 +18,20 @@ 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):** 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.
+**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.1
+npx @vibe-x/agent-better-checkpoint@0.3.3
 ```
 
 Without `--target`: installs globally. With `--target .`: project-only (skill + hooks in `.cursor/`, scripts in `.vibe-x/`), no global changes.
@@ -164,4 +167,4 @@ This should feel natural — commit as you go, like any good developer.
 
 ---
 
-**Version**: 0.3.1
+**Version**: 0.3.3