@vibe-x/agent-better-checkpoint 0.1.0

package/platform/unix/check_uncommitted.sh

@@ -0,0 +1,256 @@
+#!/usr/bin/env bash
+#
+# check_uncommitted.sh — Stop Hook: 检查未提交的变更
+#
+# 在 AI 对话结束时触发，检查工作区是否存在未提交的变更。
+# 如果存在，输出提醒信息让 AI Agent 执行 fallback checkpoint commit。
+#
+# 支持平台:
+#   - Cursor: stop hook (stdin JSON 含 workspace_roots)
+#   - Claude Code: Stop hook (stdin JSON 含 hook_event_name)
+#
+# 输出协议:
+#   - 无问题: {} (空 JSON)
+#   - 有问题 (Cursor): {"followup_message": "..."}
+#   - 有问题 (Claude Code): {"decision": "block", "reason": "..."}
+#
+# JSON 解析使用 grep+sed，不依赖 jq。
+
+set -euo pipefail
+
+# ============================================================
+# 辅助函数：简易 JSON 字段提取（不依赖 jq）
+# ============================================================
+
+# 输出允许通过的 JSON
+output_allow() {
+    echo '{}'
+    exit 0
+}
+
+# 从 JSON 中提取布尔字段值
+# Usage: json_bool "$json" "field_name" → 输出 "true" 或 "false"
+json_bool() {
+    local json="$1" field="$2"
+    if echo "$json" | grep -qE "\"${field}\"[[:space:]]*:[[:space:]]*true"; then
+        echo "true"
+    else
+        echo "false"
+    fi
+}
+
+# 从 JSON 中提取字符串字段值
+# Usage: json_string "$json" "field_name" → 输出字符串值（不含引号）
+json_string() {
+    local json="$1" field="$2"
+    echo "$json" | grep -oE "\"${field}\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" \
+        | sed -E "s/\"${field}\"[[:space:]]*:[[:space:]]*\"([^\"]*)\"/\1/" \
+        | head -1
+}
+
+# 从 JSON 的 workspace_roots / workspaceRoots 数组中提取第一个路径
+# Usage: json_workspace_root "$json" → 输出路径
+json_workspace_root() {
+    local json="$1"
+    local result=""
+
+    # 尝试 workspace_roots 和 workspaceRoots
+    for field in "workspace_roots" "workspaceRoots"; do
+        result=$(echo "$json" \
+            | grep -oE "\"${field}\"[[:space:]]*:[[:space:]]*\[[^]]*\]" \
+            | grep -oE '"[^"]*"' \
+            | tail -n +2 \
+            | head -1 \
+            | tr -d '"' || true)
+        if [[ -n "$result" ]]; then
+            echo "$result"
+            return
+        fi
+    done
+}
+
+# ============================================================
+# 平台检测
+# ============================================================
+
+detect_platform() {
+    local json="$1"
+    if [[ -z "$json" ]]; then
+        echo "unknown"
+        return
+    fi
+    # Claude Code: 有 hook_event_name 或 tool_name
+    if echo "$json" | grep -qE '"hook_event_name"|"tool_name"'; then
+        echo "claude_code"
+    else
+        echo "cursor"
+    fi
+}
+
+# ============================================================
+# Workspace Root 检测
+# ============================================================
+
+get_workspace_root() {
+    local json="$1"
+
+    # 优先从 stdin JSON 获取
+    if [[ -n "$json" ]]; then
+        local ws
+        ws=$(json_workspace_root "$json")
+        if [[ -n "$ws" ]]; then
+            echo "$ws"
+            return
+        fi
+    fi
+
+    # 回退到环境变量
+    for env_var in CURSOR_PROJECT_DIR CLAUDE_PROJECT_DIR WORKSPACE_ROOT PROJECT_ROOT; do
+        local val="${!env_var:-}"
+        if [[ -n "$val" ]]; then
+            echo "$val"
+            return
+        fi
+    done
+
+    # 最终回退到 PWD / cwd
+    echo "${PWD:-$(pwd)}"
+}
+
+# ============================================================
+# Git 操作
+# ============================================================
+
+is_git_repo() {
+    git -C "$1" rev-parse --is-inside-work-tree &>/dev/null
+}
+
+has_uncommitted_changes() {
+    local status
+    status=$(git -C "$1" status --porcelain 2>/dev/null)
+    [[ -n "$status" ]]
+}
+
+get_change_summary() {
+    local workspace="$1"
+    local max_lines="${2:-20}"
+    local output
+    output=$(git -C "$workspace" status --short 2>/dev/null || true)
+
+    if [[ -z "$output" ]]; then
+        return
+    fi
+
+    local total
+    total=$(echo "$output" | wc -l)
+
+    if [[ "$total" -gt "$max_lines" ]]; then
+        echo "$output" | head -n "$max_lines"
+        echo "  ... and $((total - max_lines)) more files"
+    else
+        echo "$output"
+    fi
+}
+
+# ============================================================
+# 输出提醒
+# ============================================================
+
+# 转义字符串用于 JSON 值（处理引号、反斜杠、换行等）
+json_escape() {
+    local str="$1"
+    str="${str//\\/\\\\}"    # 反斜杠
+    str="${str//\"/\\\"}"    # 双引号
+    str="${str//$'\n'/\\n}"  # 换行
+    str="${str//$'\r'/\\r}"  # 回车
+    str="${str//$'\t'/\\t}"  # Tab
+    echo "$str"
+}
+
+output_block() {
+    local message="$1"
+    local platform="$2"
+    local escaped
+    escaped=$(json_escape "$message")
+
+    if [[ "$platform" == "cursor" ]]; then
+        echo "{\"followup_message\":\"${escaped}\"}"
+    elif [[ "$platform" == "claude_code" ]]; then
+        echo "{\"decision\":\"block\",\"reason\":\"${escaped}\"}"
+    else
+        echo "{\"message\":\"${escaped}\"}"
+    fi
+    exit 0
+}
+
+# ============================================================
+# 主逻辑
+# ============================================================
+
+main() {
+    # 从 stdin 读取 JSON（非阻塞：如果无输入则为空）
+    local input=""
+    if [[ ! -t 0 ]]; then
+        input=$(cat)
+    fi
+
+    # Claude Code 的 stop_hook_active 防止无限循环
+    if [[ -n "$input" ]]; then
+        local stop_active
+        stop_active=$(json_bool "$input" "stop_hook_active")
+        if [[ "$stop_active" == "true" ]]; then
+            output_allow
+        fi
+    fi
+
+    # 检测平台
+    local platform
+    platform=$(detect_platform "$input")
+
+    # 获取 workspace root
+    local workspace
+    workspace=$(get_workspace_root "$input")
+
+    # 检查是否为 git 仓库
+    if ! is_git_repo "$workspace"; then
+        output_allow
+    fi
+
+    # 检查是否有未提交变更
+    if ! has_uncommitted_changes "$workspace"; then
+        output_allow
+    fi
+
+    # 获取变更摘要
+    local changes
+    changes=$(get_change_summary "$workspace")
+    local changes_indented
+    changes_indented=$(echo "$changes" | sed 's/^/  /')
+
+    # 构建提醒消息
+    local reminder
+    reminder="## ⚠️ Uncommitted Changes Detected
+
+There are uncommitted changes in the workspace. Please create a checkpoint commit before ending the conversation.
+
+**Changed files:**
+\`\`\`
+${changes_indented}
+\`\`\`
+
+**Action Required**: Run the checkpoint script to commit these changes:
+
+**macOS/Linux:**
+\`\`\`bash
+~/.agent-better-checkpoint/scripts/checkpoint.sh \"checkpoint(<scope>): <description>\" \"<user-prompt>\" --type fallback
+\`\`\`
+
+**Windows (PowerShell):**
+\`\`\`powershell
+powershell -File \"\$env:USERPROFILE/.agent-better-checkpoint/scripts/checkpoint.ps1\" \"checkpoint(<scope>): <description>\" \"<user-prompt>\" -Type fallback
+\`\`\`"
+
+    output_block "$reminder" "$platform"
+}
+
+main

package/platform/unix/checkpoint.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+#
+# checkpoint.sh — 创建语义化的 Git checkpoint commit
+#
+# AI 生成描述性内容（subject + body），本脚本负责：
+# 1. 截断 user-prompt（≤60字符，头尾截断）
+# 2. 通过 git interpret-trailers 追加元信息
+# 3. 执行 git add -A && git commit
+#
+# Usage:
+#   checkpoint.sh <message> [user-prompt] [--type auto|fallback]
+
+set -euo pipefail
+
+# ============================================================
+# 参数解析
+# ============================================================
+MESSAGE="${1:-}"
+USER_PROMPT="${2:-}"
+CHECKPOINT_TYPE="auto"
+
+shift 2 2>/dev/null || true
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --type)
+            CHECKPOINT_TYPE="${2:-auto}"
+            shift 2
+            ;;
+        *)
+            shift
+            ;;
+    esac
+done
+
+if [[ -z "$MESSAGE" ]]; then
+    echo "Error: commit message is required" >&2
+    echo "Usage: checkpoint.sh <message> [user-prompt] [--type auto|fallback]" >&2
+    exit 1
+fi
+
+# ============================================================
+# 平台检测
+# ============================================================
+detect_platform() {
+    if [[ -n "${CLAUDE_CODE:-}" ]] || command -v claude &>/dev/null; then
+        echo "claude-code"
+    elif [[ -n "${CURSOR_VERSION:-}" ]] || [[ -n "${CURSOR_TRACE_ID:-}" ]]; then
+        echo "cursor"
+    else
+        echo "unknown"
+    fi
+}
+
+AGENT_PLATFORM=$(detect_platform)
+
+# ============================================================
+# User-Prompt 截断（≤60 字符，头尾保留 + 中间省略号）
+# ============================================================
+truncate_prompt() {
+    local prompt="$1"
+    local max_len=60
+    local len=${#prompt}
+
+    if [[ $len -le $max_len ]]; then
+        echo "$prompt"
+        return
+    fi
+
+    local head_len=$(( (max_len - 3) / 2 ))
+    local tail_len=$(( max_len - 3 - head_len ))
+    local head="${prompt:0:$head_len}"
+    local tail="${prompt:$((len - tail_len)):$tail_len}"
+    echo "${head}...${tail}"
+}
+
+TRUNCATED_PROMPT=""
+if [[ -n "$USER_PROMPT" ]]; then
+    TRUNCATED_PROMPT=$(truncate_prompt "$USER_PROMPT")
+fi
+
+# ============================================================
+# 检查是否有变更
+# ============================================================
+has_changes() {
+    # staged 变更
+    if ! git diff --cached --quiet 2>/dev/null; then
+        return 0
+    fi
+    # unstaged 变更
+    if ! git diff --quiet 2>/dev/null; then
+        return 0
+    fi
+    # untracked 文件
+    if [[ -n "$(git ls-files --others --exclude-standard 2>/dev/null)" ]]; then
+        return 0
+    fi
+    return 1
+}
+
+if ! has_changes; then
+    echo "No changes to commit."
+    exit 0
+fi
+
+# ============================================================
+# git add -A
+# ============================================================
+git add -A
+
+# ============================================================
+# 构建 trailer 并提交
+# ============================================================
+TRAILER_ARGS=(
+    --trailer "Agent: ${AGENT_PLATFORM}"
+    --trailer "Checkpoint-Type: ${CHECKPOINT_TYPE}"
+)
+
+if [[ -n "$TRUNCATED_PROMPT" ]]; then
+    TRAILER_ARGS+=(--trailer "User-Prompt: ${TRUNCATED_PROMPT}")
+fi
+
+echo "$MESSAGE" | git interpret-trailers "${TRAILER_ARGS[@]}" | git commit -F -
+
+echo "Checkpoint committed successfully."

package/platform/win/check_uncommitted.ps1

@@ -0,0 +1,209 @@
+<#
+.SYNOPSIS
+    check_uncommitted.ps1 — Stop Hook: 检查未提交的变更 (Windows PowerShell)
+
+.DESCRIPTION
+    在 AI 对话结束时触发，检查工作区是否存在未提交的变更。
+    如果存在，输出提醒信息让 AI Agent 执行 fallback checkpoint commit。
+
+    支持平台:
+    - Cursor: stop hook (stdin JSON 含 workspace_roots)
+    - Claude Code: Stop hook (stdin JSON 含 hook_event_name)
+
+    输出协议:
+    - 无问题: {} (空 JSON)
+    - 有问题 (Cursor): {"followup_message": "..."}
+    - 有问题 (Claude Code): {"decision": "block", "reason": "..."}
+#>
+
+$ErrorActionPreference = "Stop"
+
+# ============================================================
+# 辅助函数
+# ============================================================
+
+function Output-Allow {
+    Write-Output '{}'
+    exit 0
+}
+
+function Output-Block {
+    param(
+        [string]$Message,
+        [string]$Platform
+    )
+
+    # 转义 JSON 字符串
+    $Escaped = $Message -replace '\\', '\\\\' `
+                        -replace '"', '\"' `
+                        -replace "`r`n", '\n' `
+                        -replace "`n", '\n' `
+                        -replace "`r", '\r' `
+                        -replace "`t", '\t'
+
+    switch ($Platform) {
+        "cursor" {
+            Write-Output "{`"followup_message`":`"$Escaped`"}"
+        }
+        "claude_code" {
+            Write-Output "{`"decision`":`"block`",`"reason`":`"$Escaped`"}"
+        }
+        default {
+            Write-Output "{`"message`":`"$Escaped`"}"
+        }
+    }
+    exit 0
+}
+
+# ============================================================
+# 平台检测
+# ============================================================
+
+function Detect-Platform {
+    param($InputData)
+
+    if (-not $InputData) {
+        return "unknown"
+    }
+    if ($InputData.PSObject.Properties["hook_event_name"] -or
+        $InputData.PSObject.Properties["tool_name"]) {
+        return "claude_code"
+    }
+    return "cursor"
+}
+
+# ============================================================
+# Workspace Root 检测
+# ============================================================
+
+function Get-WorkspaceRoot {
+    param($InputData)
+
+    # 优先从 stdin JSON 获取
+    if ($InputData) {
+        foreach ($field in @("workspace_roots", "workspaceRoots")) {
+            $roots = $null
+            try { $roots = $InputData.$field } catch {}
+            if ($roots -and $roots.Count -gt 0) {
+                return $roots[0]
+            }
+        }
+    }
+
+    # 回退到环境变量
+    foreach ($envVar in @("CURSOR_PROJECT_DIR", "CLAUDE_PROJECT_DIR", "WORKSPACE_ROOT", "PROJECT_ROOT")) {
+        $val = [Environment]::GetEnvironmentVariable($envVar)
+        if ($val) { return $val }
+    }
+
+    # 最终回退到当前目录
+    return (Get-Location).Path
+}
+
+# ============================================================
+# Git 操作
+# ============================================================
+
+function Test-GitRepo {
+    param([string]$Path)
+    try {
+        $null = git -C $Path rev-parse --is-inside-work-tree 2>$null
+        return $LASTEXITCODE -eq 0
+    }
+    catch {
+        return $false
+    }
+}
+
+function Test-UncommittedChanges {
+    param([string]$Path)
+    $status = git -C $Path status --porcelain 2>$null
+    return [bool]$status
+}
+
+function Get-ChangeSummary {
+    param(
+        [string]$Path,
+        [int]$MaxLines = 20
+    )
+
+    $output = git -C $Path status --short 2>$null
+    if (-not $output) { return "" }
+
+    $lines = $output -split "`n"
+    if ($lines.Count -gt $MaxLines) {
+        $shown = $lines[0..($MaxLines - 1)]
+        $shown += "  ... and $($lines.Count - $MaxLines) more files"
+        return ($shown -join "`n")
+    }
+    return ($lines -join "`n")
+}
+
+# ============================================================
+# 主逻辑
+# ============================================================
+
+# 从 stdin 读取 JSON
+$InputData = $null
+try {
+    $rawInput = [Console]::In.ReadToEnd()
+    if ($rawInput.Trim()) {
+        $InputData = $rawInput | ConvertFrom-Json
+    }
+}
+catch {
+    # 忽略 JSON 解析错误
+}
+
+# Claude Code 的 stop_hook_active 防止无限循环
+if ($InputData -and $InputData.PSObject.Properties["stop_hook_active"]) {
+    if ($InputData.stop_hook_active -eq $true) {
+        Output-Allow
+    }
+}
+
+# 检测平台
+$Platform = Detect-Platform -InputData $InputData
+
+# 获取 workspace root
+$Workspace = Get-WorkspaceRoot -InputData $InputData
+
+# 检查是否为 git 仓库
+if (-not (Test-GitRepo -Path $Workspace)) {
+    Output-Allow
+}
+
+# 检查是否有未提交变更
+if (-not (Test-UncommittedChanges -Path $Workspace)) {
+    Output-Allow
+}
+
+# 获取变更摘要
+$Changes = Get-ChangeSummary -Path $Workspace
+$ChangesIndented = ($Changes -split "`n" | ForEach-Object { "  $_" }) -join "`n"
+
+# 构建提醒消息
+$Reminder = @"
+## ⚠️ Uncommitted Changes Detected
+
+There are uncommitted changes in the workspace. Please create a checkpoint commit before ending the conversation.
+
+**Changed files:**
+``````
+$ChangesIndented
+``````
+
+**Action Required**: Run the checkpoint script to commit these changes:
+
+**macOS/Linux:**
+``````bash
+~/.agent-better-checkpoint/scripts/checkpoint.sh "checkpoint(<scope>): <description>" "<user-prompt>" --type fallback
+``````
+
+**Windows (PowerShell):**
+``````powershell
+powershell -File "`$env:USERPROFILE/.agent-better-checkpoint/scripts/checkpoint.ps1" "checkpoint(<scope>): <description>" "<user-prompt>" -Type fallback
+``````
+"@
+
+Output-Block -Message $Reminder -Platform $Platform

package/platform/win/checkpoint.ps1

@@ -0,0 +1,123 @@
+<#
+.SYNOPSIS
+    checkpoint.ps1 — 创建语义化的 Git checkpoint commit (Windows PowerShell)
+
+.DESCRIPTION
+    AI 生成描述性内容（subject + body），本脚本负责：
+    1. 截断 user-prompt（≤60字符，头尾截断）
+    2. 通过 git interpret-trailers 追加元信息
+    3. 执行 git add -A && git commit
+
+.PARAMETER Message
+    Full commit message (subject + blank line + body). Required.
+
+.PARAMETER UserPrompt
+    The user's original prompt/request. Optional.
+
+.PARAMETER Type
+    Checkpoint type: "auto" (default) or "fallback".
+
+.EXAMPLE
+    .\checkpoint.ps1 "checkpoint(auth): add JWT refresh" "implement token refresh"
+#>
+
+param(
+    [Parameter(Mandatory = $true, Position = 0)]
+    [string]$Message,
+
+    [Parameter(Position = 1)]
+    [string]$UserPrompt = "",
+
+    [string]$Type = "auto"
+)
+
+$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) {
+        return "cursor"
+    }
+    return "unknown"
+}
+
+$AgentPlatform = Detect-Platform
+
+# ============================================================
+# User-Prompt 截断（≤60 字符，头尾保留 + 中间省略号）
+# ============================================================
+
+function Truncate-Prompt {
+    param([string]$Prompt)
+
+    $MaxLen = 60
+    if ($Prompt.Length -le $MaxLen) {
+        return $Prompt
+    }
+
+    $HeadLen = [math]::Floor(($MaxLen - 3) / 2)
+    $TailLen = $MaxLen - 3 - $HeadLen
+    $Head = $Prompt.Substring(0, $HeadLen)
+    $Tail = $Prompt.Substring($Prompt.Length - $TailLen, $TailLen)
+    return "${Head}...${Tail}"
+}
+
+$TruncatedPrompt = ""
+if ($UserPrompt) {
+    $TruncatedPrompt = Truncate-Prompt -Prompt $UserPrompt
+}
+
+# ============================================================
+# 检查是否有变更
+# ============================================================
+
+function Test-HasChanges {
+    # staged 变更
+    $diffCached = git diff --cached --quiet 2>$null
+    if ($LASTEXITCODE -ne 0) { return $true }
+
+    # unstaged 变更
+    $diffWorking = git diff --quiet 2>$null
+    if ($LASTEXITCODE -ne 0) { return $true }
+
+    # untracked 文件
+    $untracked = git ls-files --others --exclude-standard 2>$null
+    if ($untracked) { return $true }
+
+    return $false
+}
+
+if (-not (Test-HasChanges)) {
+    Write-Host "No changes to commit."
+    exit 0
+}
+
+# ============================================================
+# git add -A
+# ============================================================
+
+git add -A
+
+# ============================================================
+# 构建 trailer 并提交
+# ============================================================
+
+$TrailerArgs = @(
+    "--trailer", "Agent: $AgentPlatform",
+    "--trailer", "Checkpoint-Type: $Type"
+)
+
+if ($TruncatedPrompt) {
+    $TrailerArgs += @("--trailer", "User-Prompt: $TruncatedPrompt")
+}
+
+# 通过管道传递消息 → git interpret-trailers → git commit
+$Message | git interpret-trailers @TrailerArgs | git commit -F -
+
+Write-Host "Checkpoint committed successfully."