diff --git a/.github/release.yml b/.github/release.yml new file mode 100644 index 0000000..b4087d6 --- /dev/null +++ b/.github/release.yml @@ -0,0 +1,18 @@ +changelog: + exclude: + labels: + - ignore-for-release + authors: + - dependabot + categories: + - title: Highlights + labels: + - highlight + - title: Improvements + labels: + - enhancement + - title: Bug Fixes + labels: + - bug + - title: Other Changes + labels: [] diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..78cf068 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,55 @@ +name: Release + +on: + push: + tags: + - 'v*' + +permissions: + contents: write + +jobs: + release: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install shellcheck + run: sudo apt-get update && sudo apt-get install -y shellcheck + + - name: Lint and test + run: make lint test + + - name: Generate checksums + run: make checksums + + - name: Create release + uses: softprops/action-gh-release@v2 + with: + body: | + **Unofficial community tool.** `cbm-tool` is an independent community wrapper for `codebase-memory-mcp`. It is not maintained, endorsed, or supported by DeusData / the upstream `codebase-memory-mcp` project. + + ## What's in this release + + - `cbm` — Linux / macOS Bash entrypoint + - `cbm.ps1` — Windows PowerShell entrypoint + - `install/install.sh` — Linux / macOS installer + - `install/install.ps1` — Windows installer + - `share/cbm/rules/codebase-memory.md` — default rule template + - `SHA256SUMS` — SHA-256 checksum manifest for all assets + - `cbm.sha256`, `cbm.ps1.sha256` — per-asset checksums + + ## Updater notes + + - `cbm update self` downloads the latest `cbm-tool` release asset and verifies its SHA-256 checksum before replacing the installed script. + - `cbm update codebase-memory-mcp` runs the official upstream updater and is separate from cbm-tool's own update mechanism. + files: | + bin/cbm + bin/cbm.ps1 + install/install.sh + install/install.ps1 + share/cbm/rules/codebase-memory.md + SHA256SUMS + bin/cbm.sha256 + bin/cbm.ps1.sha256 diff --git a/.gitignore b/.gitignore index 3880ec4..0364d51 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,7 @@ desktop.ini # Test artifacts tests/tmp/ tests/fixtures/ + +# Release checksum artifacts (generated by make checksums and CI) +SHA256SUMS +*.sha256 diff --git a/Makefile b/Makefile index 35f755e..477f182 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: install uninstall test lint +.PHONY: install uninstall test lint checksums PREFIX ?= $(HOME)/.local BIN_DIR = $(PREFIX)/bin @@ -14,3 +14,8 @@ test: lint: shellcheck bin/cbm install/install.sh tests/test_unix.sh + +checksums: + sha256sum bin/cbm bin/cbm.ps1 install/install.sh install/install.ps1 share/cbm/rules/codebase-memory.md > SHA256SUMS + sha256sum bin/cbm | awk '{print $$1}' > bin/cbm.sha256 + sha256sum bin/cbm.ps1 | awk '{print $$1}' > bin/cbm.ps1.sha256 diff --git a/README.md b/README.md index f2002bd..d9b2384 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,14 @@ # cbm -Cross-platform convenience wrapper for the [`codebase-memory-mcp`](https://github.com/DeusData/codebase-memory-mcp) `index_repository` command. +> **Unofficial community tool.** `cbm-tool` is an independent community wrapper for [`codebase-memory-mcp`](https://github.com/DeusData/codebase-memory-mcp). It is not maintained, endorsed, or supported by DeusData / the upstream `codebase-memory-mcp` project. + +Cross-platform convenience wrapper for the `codebase-memory-mcp` `index_repository` command. Supports **Linux**, **macOS**, and **Windows** (PowerShell). ## What it does -`cbm` makes it easy to index a local git repository into the `codebase-memory-mcp` knowledge graph, with sensible defaults and a friendlier CLI. +`cbm` is an unofficial community wrapper that makes it easy to index a local git repository into the `codebase-memory-mcp` knowledge graph, with sensible defaults and a friendlier CLI. It also includes a `setup` command that configures local AI editors (Claude Code, Cursor, Codex CLI, Cline, Windsurf) to use `codebase-memory-mcp` and to prefer the knowledge graph when exploring code. @@ -55,6 +57,8 @@ cbm.ps1 . ### Configure your AI editors +> **Back up your editor configs first.** `cbm setup` modifies editor configuration and rules files. Run `cbm setup --dry-run` to preview the changes, and back up the listed files before applying them. + ```bash # Auto-detect installed editors and configure them cbm setup @@ -74,16 +78,18 @@ The rule template lives at [`share/cbm/rules/codebase-memory.md`](share/cbm/rule ### Update cbm or codebase-memory-mcp ```bash -# Update cbm itself from GitHub +# Update cbm-tool itself from the latest GitHub release (verifies SHA-256 checksum) cbm update self # Preview the self-update cbm update self --dry-run -# Update codebase-memory-mcp +# Update codebase-memory-mcp via its own official updater cbm update codebase-memory-mcp ``` +`cbm update self` downloads the latest release asset of `cbm-tool` from GitHub and verifies its SHA-256 checksum before replacing the installed script. `cbm update codebase-memory-mcp` runs the official upstream updater. + See [docs/INSTALL.md](docs/INSTALL.md) for detailed installation steps and [docs/USAGE.md](docs/USAGE.md) for the full command reference. 中文文档：[README.zh-CN.md](README.zh-CN.md) | [安装指南](docs/INSTALL.zh-CN.md) | [使用指南](docs/USAGE.zh-CN.md)。 diff --git a/README.zh-CN.md b/README.zh-CN.md index 39f4a1c..853aaf4 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,12 +1,14 @@ # cbm +> **非官方社区工具。** `cbm-tool` 是 [`codebase-memory-mcp`](https://github.com/DeusData/codebase-memory-mcp) 的独立社区封装工具，并非由 DeusData 或上游 `codebase-memory-mcp` 项目维护、认可或支持。 + [`codebase-memory-mcp`](https://github.com/DeusData/codebase-memory-mcp) 的跨平台便捷命令行封装工具。 支持 **Linux**、**macOS** 和 **Windows**（PowerShell）。 ## 功能 -`cbm` 让你可以用更友好的命令行界面，把本地 Git 仓库索引到 `codebase-memory-mcp` 知识图谱中。 +`cbm` 是一个非官方社区封装工具，让你可以用更友好的命令行界面，把本地 Git 仓库索引到 `codebase-memory-mcp` 知识图谱中。 它还包含一个 `setup` 命令，可以配置本地 AI 编辑器（Claude Code、Cursor、Codex CLI、Cline、Windsurf）接入 `codebase-memory-mcp`，并在探索代码时优先使用知识图谱。 @@ -55,6 +57,8 @@ cbm.ps1 . ### 配置你的 AI 编辑器 +> **请先备份编辑器配置。**`cbm setup` 会修改编辑器配置与规则文件。运行 `cbm setup --dry-run` 预览将修改的文件，确认后再备份并应用。 + ```bash # 自动检测已安装的编辑器并配置 cbm setup @@ -74,16 +78,18 @@ cbm setup --uninstall ### 更新 cbm 或 codebase-memory-mcp ```bash -# 从 GitHub 更新 cbm 自身 +# 从 cbm-tool 最新 GitHub Release 更新自身（会校验 SHA-256 校验和） cbm update self # 预览更新 cbm update self --dry-run -# 更新 codebase-memory-mcp +# 通过 codebase-memory-mcp 自身的官方更新器进行更新 cbm update codebase-memory-mcp ``` +`cbm update self` 从 GitHub 下载 `cbm-tool` 的最新 Release 资源，并在替换本地脚本前校验其 SHA-256 校验和。`cbm update codebase-memory-mcp` 则调用上游官方更新器。 + 完整文档： - [English Usage](docs/USAGE.md) / [中文使用指南](docs/USAGE.zh-CN.md) diff --git a/bin/cbm b/bin/cbm index c2ad42c..8ef554f 100755 --- a/bin/cbm +++ b/bin/cbm @@ -1,6 +1,10 @@ #!/usr/bin/env bash # cbm - Convenience wrapper for codebase-memory-mcp # +# Unofficial community tool: cbm-tool is an independent community wrapper for +# codebase-memory-mcp. It is not maintained, endorsed, or supported by DeusData +# or the upstream codebase-memory-mcp project. +# # Usage: cbm [OPTIONS] # cbm setup [OPTIONS] @@ -13,16 +17,18 @@ VALID_MODES="full moderate fast cross-repo-intelligence" SETUP_EDITORS="claude cursor codex cline windsurf" CBM_RULE_MARKER_START="" CBM_RULE_MARKER_END="" -VERSION="1.0.0" +VERSION="1.0.1" usage() { cat < $PROG setup [OPTIONS] - $PROG update [OPTIONS] + $PROG update [OPTIONS] + +Unofficial community tool — independent wrapper for codebase-memory-mcp. Index a local repository using codebase-memory-mcp, configure local AI -editors, or update cbm / codebase-memory-mcp. +editors, or update cbm-tool / codebase-memory-mcp. Index options: -m, --mode MODE Index mode: full | moderate | fast | cross-repo-intelligence @@ -35,8 +41,8 @@ Index options: -v, -V, --version Show version Update options: - self Update cbm itself from GitHub - codebase-memory-mcp Update codebase-memory-mcp via its own updater + self, cbm-tool Update cbm-tool itself from its GitHub release + codebase-memory-mcp Update codebase-memory-mcp via its own official updater -y, --yes Skip confirmation prompts -n, --dry-run Show what would be done without making changes -h, --help Show update help @@ -69,6 +75,9 @@ Usage: $PROG setup [OPTIONS] Configure local AI editors (Claude Code, Cursor, Codex CLI, Cline, Windsurf) to use codebase-memory-mcp for code exploration. +This command modifies editor configuration and rules files. Back up the +listed files before applying, or run with --dry-run to preview. + Options: -e, --editor EDITOR Configure only this editor ($SETUP_EDITORS) -u, --uninstall Remove codebase-memory-mcp configuration and rules @@ -83,13 +92,14 @@ EOF update_usage() { cat < [OPTIONS] +Usage: $PROG update [OPTIONS] -Update cbm itself from GitHub, or update codebase-memory-mcp via its own updater. +Update cbm-tool itself from its GitHub release, or run the official +codebase-memory-mcp updater. Targets: - self Download the latest cbm script from the GitHub repo - codebase-memory-mcp Run \`codebase-memory-mcp update -y\` + self, cbm-tool Download the latest cbm-tool release asset (SHA-256 verified) + codebase-memory-mcp Run the official codebase-memory-mcp updater Options: -y, --yes Skip confirmation prompts @@ -515,6 +525,28 @@ detect_editors() { echo "${editors# }" } +# Return the list of files that setup would touch for a given editor. +setup_affected_files() { + local editor="$1" + case "$editor" in + claude) + echo "$HOME/.claude/.mcp.json $HOME/.claude/skills/codebase-memory.md" + ;; + cursor) + echo "$HOME/.cursor/mcp.json $HOME/.cursorrules" + ;; + codex) + echo "$HOME/.codex/config.toml $HOME/.codex/AGENTS.md" + ;; + cline) + echo "$HOME/.clinerules" + ;; + windsurf) + echo "$HOME/.windsurfrules" + ;; + esac +} + # Run setup or uninstall for detected or selected editors. cmd_setup() { local editor="" @@ -594,6 +626,23 @@ cmd_setup() { else log "will configure: $editors" fi + + # Collect affected files for backup warning. + local affected_files="" + for ed in $editors; do + affected_files="$affected_files $(setup_affected_files "$ed")" + done + # Normalize whitespace and de-duplicate while preserving order. + affected_files=$(echo "$affected_files" | tr ' ' '\n' | awk '!seen[$0]++' | tr '\n' ' ' | sed 's/^ *//;s/ *$//') + if [[ -n "$affected_files" ]]; then + if [[ "$dry_run" == "true" ]]; then + log "[dry-run] would modify the following files: $affected_files" + else + log "the following files will be modified: $affected_files" + log "back them up manually, or run with --dry-run to preview" + fi + fi + if [[ "$dry_run" != "true" && "$yes" != "true" ]]; then read -rp "Proceed? [y/N] " reply [[ "$reply" =~ ^[Yy]$ ]] || { log "cancelled"; exit 0; } @@ -626,7 +675,7 @@ cmd_setup() { fi } -# Download the latest cbm script from GitHub and replace the installed one. +# Download the latest cbm-tool release asset and replace the installed script. # Args: dry_run yes update_self() { local dry_run="$1" @@ -641,23 +690,52 @@ update_self() { local real_path real_path=$(readlink -f "$cbm_path" 2>/dev/null) || real_path="$cbm_path" - local url="https://raw.githubusercontent.com/fxjs/cbm-tool/main/bin/cbm" + local base_url="https://github.com/fxjs/cbm-tool/releases/latest/download" + local script_url="${base_url}/cbm" + local checksum_url="${base_url}/cbm.sha256" local tmp="${real_path}.tmp" + local tmp_checksum="${real_path}.tmp.sha256" log "current cbm: $real_path" - log "download URL: $url" + log "download URL: $script_url" + log "checksum URL: $checksum_url" if [[ "$dry_run" == "true" ]]; then - log "[dry-run] would download latest cbm to $real_path" + log "[dry-run] would download latest cbm-tool release to $real_path" return 0 fi if [[ "$yes" != "true" ]]; then - read -rp "Update $real_path from GitHub? [y/N] " reply + read -rp "Update $real_path from the latest cbm-tool release? [y/N] " reply [[ "$reply" =~ ^[Yy]$ ]] || { log "cancelled"; exit 0; } fi - curl -fsSL -o "$tmp" "$url" || fail "failed to download latest cbm" + curl -fsSL -o "$tmp" "$script_url" || fail "failed to download latest cbm-tool release" + curl -fsSL -o "$tmp_checksum" "$checksum_url" || { + rm -f "$tmp" + fail "failed to download checksum for latest cbm-tool release" + } + + local expected_hash + expected_hash=$(awk '{print $1}' "$tmp_checksum") + if [[ -z "$expected_hash" ]]; then + rm -f "$tmp" "$tmp_checksum" + fail "could not read expected checksum" + fi + + local actual_hash + if command -v sha256sum >/dev/null 2>&1; then + actual_hash=$(sha256sum "$tmp" | awk '{print $1}') + else + actual_hash=$(shasum -a 256 "$tmp" | awk '{print $1}') + fi + + if [[ "$actual_hash" != "$expected_hash" ]]; then + rm -f "$tmp" "$tmp_checksum" + fail "checksum verification failed for downloaded cbm (expected $expected_hash, got $actual_hash)" + fi + + rm -f "$tmp_checksum" if ! bash -n "$tmp"; then rm -f "$tmp" @@ -666,7 +744,7 @@ update_self() { chmod +x "$tmp" mv "$tmp" "$real_path" - log "updated cbm to latest version" + log "updated cbm-tool to latest release" } # Update codebase-memory-mcp via its own updater. @@ -725,17 +803,17 @@ cmd_update() { esac done - [[ -n "$target" ]] || fail "update target is required (self | codebase-memory-mcp)" + [[ -n "$target" ]] || fail "update target is required (self | cbm-tool | codebase-memory-mcp)" case "$target" in - self) + self|cbm-tool) update_self "$dry_run" "$yes" ;; codebase-memory-mcp) update_codebase_memory_mcp "$dry_run" ;; *) - fail "invalid update target '$target'. Valid targets: self, codebase-memory-mcp" + fail "invalid update target '$target'. Valid targets: self, cbm-tool, codebase-memory-mcp" ;; esac } diff --git a/bin/cbm.ps1 b/bin/cbm.ps1 index d4f99b7..ee6df0d 100755 --- a/bin/cbm.ps1 +++ b/bin/cbm.ps1 @@ -1,6 +1,10 @@ #!/usr/bin/env pwsh # cbm.ps1 - Convenience wrapper for codebase-memory-mcp (Windows) # +# Unofficial community tool: cbm-tool is an independent community wrapper for +# codebase-memory-mcp. It is not maintained, endorsed, or supported by DeusData +# or the upstream codebase-memory-mcp project. +# # Usage: cbm.ps1 [OPTIONS] # cbm.ps1 setup [OPTIONS] @@ -11,17 +15,19 @@ $SETUP_EDITORS = @("claude", "cursor", "codex", "cline", "windsurf") $CBM_RULE_MARKER_START = "" $CBM_RULE_MARKER_END = "" $UI_URL = "http://127.0.0.1:9749/" -$VERSION = "1.0.0" +$VERSION = "1.0.1" $GITHUB_REPO = "fxjs/cbm-tool" function Show-Usage { @" Usage: $PROG [OPTIONS] $PROG setup [OPTIONS] - $PROG update [OPTIONS] + $PROG update [OPTIONS] + +Unofficial community tool — independent wrapper for codebase-memory-mcp. Index a local repository using codebase-memory-mcp, configure local AI -editors, or update cbm / codebase-memory-mcp. +editors, or update cbm-tool / codebase-memory-mcp. Index options: -Mode MODE Index mode: full | moderate | fast | cross-repo-intelligence @@ -34,11 +40,11 @@ Index options: -Version Show version Update options: - self Update cbm itself from GitHub - codebase-memory-mcp Update codebase-memory-mcp via its own updater - -Yes Skip confirmation prompts - -DryRun Show what would be done without making changes - -Help Show update help + self, cbm-tool Update cbm-tool itself from its GitHub release + codebase-memory-mcp Update codebase-memory-mcp via its own official updater + -Yes Skip confirmation prompts + -DryRun Show what would be done without making changes + -Help Show update help Setup options: -Editor EDITOR Configure only this editor ($($SETUP_EDITORS -join ', ')) @@ -68,6 +74,9 @@ Usage: $PROG setup [OPTIONS] Configure local AI editors (Claude Code, Cursor, Codex CLI, Cline, Windsurf) to use codebase-memory-mcp for code exploration. +This command modifies editor configuration and rules files. Back up the +listed files before applying, or run with -DryRun to preview. + Options: -Editor EDITOR Configure only this editor ($($SETUP_EDITORS -join ', ')) -Uninstall Remove codebase-memory-mcp configuration and rules @@ -82,18 +91,19 @@ Detected editors are configured automatically unless -Editor is given. function Show-UpdateUsage { @" -Usage: $PROG update [OPTIONS] +Usage: $PROG update [OPTIONS] -Update cbm itself from GitHub, or update codebase-memory-mcp via its own updater. +Update cbm-tool itself from its GitHub release, or run the official +codebase-memory-mcp updater. Targets: - self Download the latest cbm.ps1 script from the GitHub repo - codebase-memory-mcp Run `codebase-memory-mcp update -y` + self, cbm-tool Download the latest cbm-tool release asset (SHA-256 verified) + codebase-memory-mcp Run the official codebase-memory-mcp updater Options: - -Yes Skip confirmation prompts - -DryRun Show what would be done without making changes - -Help Show this help + -Yes Skip confirmation prompts + -DryRun Show what would be done without making changes + -Help Show this help "@ } @@ -639,6 +649,40 @@ function Read-SetupArgs { } } +function Get-SetupAffectedFiles { + param([string]$Editor) + + switch ($Editor) { + "claude" { + return @( + "$env:USERPROFILE/.claude/.mcp.json", + "$env:USERPROFILE/.claude/skills/codebase-memory.md" + ) + } + "cursor" { + return @( + "$env:USERPROFILE/.cursor/mcp.json", + "$env:USERPROFILE/.cursorrules" + ) + } + "codex" { + return @( + "$env:USERPROFILE/.codex/config.toml", + "$env:USERPROFILE/.codex/AGENTS.md" + ) + } + "cline" { + return @("$env:USERPROFILE/.clinerules") + } + "windsurf" { + return @("$env:USERPROFILE/.windsurfrules") + } + default { + return @() + } + } +} + function Invoke-CmdSetup { $parsed = Read-SetupArgs -RawArgs $SetupArgs $editor = $parsed.Editor @@ -673,6 +717,23 @@ function Invoke-CmdSetup { } else { Write-Log "will configure: $($editors -join ', ')" } + + # Collect affected files for backup warning. + $affectedFiles = @() + foreach ($ed in $editors) { + $affectedFiles += Get-SetupAffectedFiles -Editor $ed + } + $affectedFiles = $affectedFiles | Select-Object -Unique + if ($affectedFiles.Count -gt 0) { + $fileList = $affectedFiles -join ', ' + if ($dryRun) { + Write-Log "[dry-run] would modify the following files: $fileList" + } else { + Write-Log "the following files will be modified: $fileList" + Write-Log "back them up manually, or run with -DryRun to preview" + } + } + if (-not $dryRun -and -not $yes) { $reply = Read-Host "Proceed? [y/N]" if ($reply -notmatch '^[Yy]$') { @@ -720,19 +781,23 @@ function Update-Self { } $target = $cmd.Source - $url = "https://raw.githubusercontent.com/$GITHUB_REPO/main/bin/cbm.ps1" + $baseUrl = "https://github.com/$GITHUB_REPO/releases/latest/download" + $scriptUrl = "$baseUrl/cbm.ps1" + $checksumUrl = "$baseUrl/cbm.ps1.sha256" $tmp = "$target.tmp" + $tmpChecksum = "$target.tmp.sha256" Write-Log "current cbm.ps1: $target" - Write-Log "download URL: $url" + Write-Log "download URL: $scriptUrl" + Write-Log "checksum URL: $checksumUrl" if ($DryRun) { - Write-Log "[dry-run] would download latest cbm.ps1 to $target" + Write-Log "[dry-run] would download latest cbm-tool release to $target" return } if (-not $Yes) { - $reply = Read-Host "Update $target from GitHub? [y/N]" + $reply = Read-Host "Update $target from the latest cbm-tool release? [y/N]" if ($reply -notmatch '^[Yy]$') { Write-Log "cancelled" exit 0 @@ -740,11 +805,32 @@ function Update-Self { } try { - Invoke-WebRequest -Uri $url -OutFile $tmp -UseBasicParsing + Invoke-WebRequest -Uri $scriptUrl -OutFile $tmp -UseBasicParsing + } catch { + Write-Fail "failed to download latest cbm-tool release: $_" + } + + try { + Invoke-WebRequest -Uri $checksumUrl -OutFile $tmpChecksum -UseBasicParsing } catch { - Write-Fail "failed to download latest cbm.ps1: $_" + Remove-Item $tmp -Force + Write-Fail "failed to download checksum for latest cbm-tool release: $_" } + $expectedHash = (Get-Content $tmpChecksum -TotalCount 1) -split '\s+' | Select-Object -First 1 + if (-not $expectedHash) { + Remove-Item $tmp, $tmpChecksum -Force + Write-Fail "could not read expected checksum" + } + + $actualHash = (Get-FileHash -Path $tmp -Algorithm SHA256).Hash + if ($actualHash -ne $expectedHash) { + Remove-Item $tmp, $tmpChecksum -Force + Write-Fail "checksum verification failed for downloaded cbm.ps1 (expected $expectedHash, got $actualHash)" + } + + Remove-Item $tmpChecksum -Force + # Basic sanity check: file should start with shebang. $firstLine = Get-Content $tmp -TotalCount 1 if ($firstLine -notmatch '^#\!.*pwsh') { @@ -753,7 +839,7 @@ function Update-Self { } Move-Item -Path $tmp -Destination $target -Force - Write-Log "updated cbm.ps1 to latest version" + Write-Log "updated cbm-tool to latest release" } function Update-CodebaseMemoryMcp { @@ -820,13 +906,13 @@ function Invoke-CmdUpdate { $dryRun = $parsed.DryRun if (-not $target) { - Write-Fail "update target is required (self | codebase-memory-mcp)" + Write-Fail "update target is required (self | cbm-tool | codebase-memory-mcp)" } switch ($target) { - "self" { Update-Self -DryRun $dryRun -Yes $yes } + { $_ -in "self", "cbm-tool" } { Update-Self -DryRun $dryRun -Yes $yes } "codebase-memory-mcp" { Update-CodebaseMemoryMcp -DryRun $dryRun } - default { Write-Fail "invalid update target '$target'. Valid targets: self, codebase-memory-mcp" } + default { Write-Fail "invalid update target '$target'. Valid targets: self, cbm-tool, codebase-memory-mcp" } } } diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 7275279..e3d43a5 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -2,6 +2,8 @@ > [中文安装指南](INSTALL.zh-CN.md) +> **Unofficial community tool.** `cbm-tool` is an independent community wrapper for `codebase-memory-mcp`. It is not maintained, endorsed, or supported by DeusData / the upstream project. + ## Linux ### 1. Install dependencies @@ -112,6 +114,8 @@ cbm.ps1 -Mode fast C:\path\to\repo > powershell -ExecutionPolicy Bypass .\install\install.ps1 > ``` +> **Note:** Release assets on GitHub include a `SHA256SUMS` file and per-asset `.sha256` files. You can verify downloads with `sha256sum -c SHA256SUMS` on Linux/macOS or `Get-FileHash` on Windows. + ## Uninstall ### Linux / macOS diff --git a/docs/INSTALL.zh-CN.md b/docs/INSTALL.zh-CN.md index 9590887..59660ed 100644 --- a/docs/INSTALL.zh-CN.md +++ b/docs/INSTALL.zh-CN.md @@ -2,6 +2,8 @@ > [English Installation Guide](INSTALL.md) +> **非官方社区工具。** `cbm-tool` 是 `codebase-memory-mcp` 的独立社区封装工具，并非由 DeusData 或上游项目维护、认可或支持。 + ## Linux ### 1. 安装依赖 @@ -112,6 +114,8 @@ cbm.ps1 -Mode fast C:\path\to\repo > powershell -ExecutionPolicy Bypass .\install\install.ps1 > ``` +> **注意：** GitHub Release 资源包含 `SHA256SUMS` 文件以及每个资源的 `.sha256` 文件。在 Linux/macOS 上可用 `sha256sum -c SHA256SUMS` 校验，Windows 上可用 `Get-FileHash`。 + ## 卸载 ### Linux / macOS diff --git a/docs/USAGE.md b/docs/USAGE.md index 6303c39..22fe9d2 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -2,6 +2,8 @@ > [中文使用指南](USAGE.zh-CN.md) +> **Unofficial community tool.** `cbm-tool` is an independent community wrapper for [`codebase-memory-mcp`](https://github.com/DeusData/codebase-memory-mcp). It is not maintained, endorsed, or supported by DeusData / the upstream project. + `cbm` is a convenience CLI wrapper around [`codebase-memory-mcp`](https://github.com/DeusData/codebase-memory-mcp). It works on **Linux**, **macOS**, and **Windows** (PowerShell). ## Quick Start @@ -14,6 +16,14 @@ cbm . .\bin\cbm.ps1 . ``` +## Before you run `cbm setup` + +`cbm setup` modifies editor configuration and rules files. To avoid surprises: + +1. **Preview first.** Run `cbm setup --dry-run` to see exactly which files would change and what would be written. `--dry-run` does not modify any files. +2. **Back up the listed files.** The files that will be touched depend on which editors are detected (or selected with `--editor`). Make a manual copy of each file shown in the preview before running without `--dry-run`. +3. **Use `--yes` only after previewing.** The confirmation prompt is skipped with `--yes`, so verify the dry-run output first. + ## Command Reference ```text @@ -139,7 +149,11 @@ rule set that reminds the AI to prefer the knowledge graph when exploring code. `cbm setup --uninstall` removes the MCP server entry and the rule block that `cbm setup` previously added. Other editor settings and rules are left untouched. -Supported editors: +**Back up the listed files before running.** `cbm setup` will touch the files +shown in the table below for each detected or selected editor. Run +`cbm setup --dry-run` first to see which files apply to your system. + +Supported editors and the files they use: | Editor | MCP config | Rules file | |--------|-----------|------------| @@ -151,24 +165,26 @@ Supported editors: Run `cbm setup --dry-run` to preview the changes before applying them. -## `cbm update` — Update cbm or codebase-memory-mcp +## `cbm update` — Update cbm-tool or codebase-memory-mcp ```bash -# Update cbm itself from the GitHub repo +# Update cbm-tool itself from the latest GitHub release (SHA-256 checksum verified) cbm update self # Preview the self-update cbm update self --dry-run -# Update codebase-memory-mcp via its own updater +# Update codebase-memory-mcp via its own official updater cbm update codebase-memory-mcp ``` -`cbm update self` downloads the latest `bin/cbm` from `https://github.com/fxjs/cbm-tool` -and replaces the installed binary. A syntax check is run on the downloaded file -before replacing the current version. +`cbm update self` downloads the latest `cbm-tool` release asset from GitHub, +verifies its SHA-256 checksum, runs a syntax check, and then replaces the +installed script. -`cbm update codebase-memory-mcp` simply runs `codebase-memory-mcp update -y`. +`cbm update codebase-memory-mcp` simply runs the official upstream command +`codebase-memory-mcp update -y`. This is the official updater, separate from +cbm-tool's own update mechanism. ## Index Modes diff --git a/docs/USAGE.zh-CN.md b/docs/USAGE.zh-CN.md index 6d677bb..449c7a5 100644 --- a/docs/USAGE.zh-CN.md +++ b/docs/USAGE.zh-CN.md @@ -2,6 +2,8 @@ > [English Usage Guide](USAGE.md) +> **非官方社区工具。** `cbm-tool` 是 [`codebase-memory-mcp`](https://github.com/DeusData/codebase-memory-mcp) 的独立社区封装工具，并非由 DeusData 或上游项目维护、认可或支持。 + `cbm` 是 [`codebase-memory-mcp`](https://github.com/DeusData/codebase-memory-mcp) 的便捷命令行封装工具。 支持 **Linux**、**macOS** 和 **Windows**（PowerShell）。 @@ -16,6 +18,14 @@ cbm . .\bin\cbm.ps1 . ``` +## 运行 `cbm setup` 之前 + +`cbm setup` 会修改编辑器配置与规则文件。为避免误操作： + +1. **先预览。** 运行 `cbm setup --dry-run` 查看会修改哪些文件、写入什么内容。`--dry-run` 不会修改任何文件。 +2. **备份列出的文件。** 实际修改的文件取决于检测到的编辑器（或用 `--editor` 指定的编辑器）。在去掉 `--dry-run` 运行前，请手动备份预览中列出的每个文件。 +3. **确认后再使用 `--yes`。** `--yes` 会跳过确认提示，因此请先确认 `--dry-run` 的输出。 + ## 命令参考 ```text @@ -139,7 +149,9 @@ cbm -V `cbm setup --uninstall` 会移除之前由 `cbm setup` 添加的 MCP server 条目和规则块，不会改动编辑器的其他设置或规则。 -支持的编辑器： +**运行前请备份下表列出的文件。** `cbm setup` 会触及每个检测到或指定编辑器对应的下述文件。先运行 `cbm setup --dry-run`，确认哪些文件会在你的系统上被修改。 + +支持的编辑器及其使用的文件： | 编辑器 | MCP 配置 | 规则文件 | |--------|---------|----------| @@ -151,23 +163,22 @@ cbm -V 执行 `cbm setup --dry-run` 可以先预览即将进行的修改。 -## `cbm update` — 更新 cbm 或 codebase-memory-mcp +## `cbm update` — 更新 cbm-tool 或 codebase-memory-mcp ```bash -# 从 GitHub 仓库更新 cbm 自身 +# 从 cbm-tool 最新 GitHub Release 更新自身（会校验 SHA-256 校验和） cbm update self # 预览更新 cbm update self --dry-run -# 通过 codebase-memory-mcp 自己的更新器更新它 +# 通过 codebase-memory-mcp 自身的官方更新器进行更新 cbm update codebase-memory-mcp ``` -`cbm update self` 会从 `https://github.com/fxjs/cbm-tool` 下载最新的 `bin/cbm`， -替换当前安装的脚本。替换前会先对下载文件做语法检查。 +`cbm update self` 从 GitHub 下载 `cbm-tool` 的最新 Release 资源，校验 SHA-256 校验和、做语法检查，然后替换本地脚本。 -`cbm update codebase-memory-mcp` 等价于运行 `codebase-memory-mcp update -y`。 +`cbm update codebase-memory-mcp` 等价于运行官方上游命令 `codebase-memory-mcp update -y`。这是官方更新器，与 cbm-tool 自身的更新机制彼此独立。 ## 索引模式 diff --git a/tests/test_unix.sh b/tests/test_unix.sh index 6298d11..f16ce32 100755 --- a/tests/test_unix.sh +++ b/tests/test_unix.sh @@ -45,10 +45,13 @@ output="$($CBM setup --help 2>&1)" [[ "$output" == *"editor"* ]] || fail "setup --help should mention editor" pass "setup --help prints usage" -# Test 6: cbm setup --dry-run --editor claude exits 0 +# Test 6: cbm setup --dry-run --editor claude exits 0 and warns about affected files output="$($CBM setup --dry-run --yes --editor claude 2>&1)" [[ "$output" == *"Claude Code"* ]] || fail "setup --editor claude should configure Claude Code" -pass "setup dry-run for claude" +[[ "$output" == *"would modify"* ]] || fail "setup dry-run should list affected files" +[[ "$output" == *".claude/.mcp.json"* ]] || fail "setup dry-run should mention ~/.claude/.mcp.json" +[[ "$output" == *".claude/skills/codebase-memory.md"* ]] || fail "setup dry-run should mention ~/.claude/skills/codebase-memory.md" +pass "setup dry-run for claude lists affected files" # Test 7: cbm setup with invalid editor fails if "$CBM" setup --dry-run --yes --editor invalid-editor 2>/dev/null; then @@ -75,18 +78,18 @@ pass "uninstall dry-run exits 0" # Test 11: cbm --version prints version output="$($CBM --version 2>&1)" -[[ "$output" == "1.0.0" ]] || fail "--version should print 1.0.0" -pass "--version prints 1.0.0" +[[ "$output" == "1.0.1" ]] || fail "--version should print 1.0.1" +pass "--version prints 1.0.1" # Test 12: cbm -v prints version output="$($CBM -v 2>&1)" -[[ "$output" == "1.0.0" ]] || fail "-v should print 1.0.0" -pass "-v prints 1.0.0" +[[ "$output" == "1.0.1" ]] || fail "-v should print 1.0.1" +pass "-v prints 1.0.1" # Test 13: cbm -V prints version output="$($CBM -V 2>&1)" -[[ "$output" == "1.0.0" ]] || fail "-V should print 1.0.0" -pass "-V prints 1.0.0" +[[ "$output" == "1.0.1" ]] || fail "-V should print 1.0.1" +pass "-V prints 1.0.1" # Test 14: cbm update --help prints update usage output="$($CBM update --help 2>&1)" @@ -97,6 +100,8 @@ pass "update --help prints usage" # Test 15: cbm update self --dry-run exits 0 output="$($CBM update self --dry-run 2>&1)" [[ "$output" == *"download URL"* ]] || fail "update self --dry-run should show download URL" +[[ "$output" == *"checksum URL"* ]] || fail "update self --dry-run should show checksum URL" +[[ "$output" == *"github.com/fxjs/cbm-tool/releases/latest/download/cbm"* ]] || fail "update self --dry-run should use release asset URL" pass "update self dry-run" # Test 16: cbm update codebase-memory-mcp --dry-run exits 0 diff --git a/tests/test_windows.ps1 b/tests/test_windows.ps1 index 3cadd8c..6badfd9 100755 --- a/tests/test_windows.ps1 +++ b/tests/test_windows.ps1 @@ -52,7 +52,10 @@ Pass "setup -Help prints usage" $output = & $CBM setup -DryRun -Yes -Editor claude 2>&1 if ($LASTEXITCODE -ne 0) { Fail "setup dry-run for claude should exit 0" } if ($output -notmatch "Claude Code") { Fail "setup -Editor claude should configure Claude Code" } -Pass "setup dry-run for claude" +if ($output -notmatch "would modify") { Fail "setup dry-run should list affected files" } +if ($output -notmatch "\.claude/\.mcp\.json") { Fail "setup dry-run should mention ~/.claude/.mcp.json" } +if ($output -notmatch "\.claude/skills/codebase-memory\.md") { Fail "setup dry-run should mention ~/.claude/skills/codebase-memory.md" } +Pass "setup dry-run for claude lists affected files" # Test 7: invalid editor fails & $CBM setup -DryRun -Yes -Editor invalid-editor 2>&1 | Out-Null @@ -73,20 +76,20 @@ Pass "uninstall dry-run exits 0" # Test 10: -Version prints version $output = & $CBM -Version 2>&1 if ($LASTEXITCODE -ne 0) { Fail "-Version should exit 0" } -if ($output -notmatch "^1\.0\.0$") { Fail "-Version should print 1.0.0" } -Pass "-Version prints 1.0.0" +if ($output -notmatch "^1\.0\.1$") { Fail "-Version should print 1.0.1" } +Pass "-Version prints 1.0.1" # Test 11: --version prints version $output = & $CBM --version 2>&1 if ($LASTEXITCODE -ne 0) { Fail "--version should exit 0" } -if ($output -notmatch "^1\.0\.0$") { Fail "--version should print 1.0.0" } -Pass "--version prints 1.0.0" +if ($output -notmatch "^1\.0\.1$") { Fail "--version should print 1.0.1" } +Pass "--version prints 1.0.1" # Test 12: -v prints version $output = & $CBM -v 2>&1 if ($LASTEXITCODE -ne 0) { Fail "-v should exit 0" } -if ($output -notmatch "^1\.0\.0$") { Fail "-v should print 1.0.0" } -Pass "-v prints 1.0.0" +if ($output -notmatch "^1\.0\.1$") { Fail "-v should print 1.0.1" } +Pass "-v prints 1.0.1" # Test 13: update -Help prints update usage $output = & $CBM update -Help 2>&1 @@ -99,6 +102,8 @@ Pass "update -Help prints usage" $output = & $CBM update self -DryRun 2>&1 if ($LASTEXITCODE -ne 0) { Fail "update self -DryRun should exit 0" } if ($output -notmatch "download URL") { Fail "update self -DryRun should show download URL" } +if ($output -notmatch "checksum URL") { Fail "update self -DryRun should show checksum URL" } +if ($output -notmatch "github.com/fxjs/cbm-tool/releases/latest/download/cbm.ps1") { Fail "update self -DryRun should use release asset URL" } Pass "update self dry-run" # Test 15: update codebase-memory-mcp -DryRun exits 0