nexusx 2.0.0__tar.gz

nexusx-2.0.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: Test
+
+on:
+  push:
+    paths:
+      - 'src/nexusx/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run linter
+        run: uv run ruff check src/
+
+      - name: Test with pytest
+        run: uv run pytest tests/ -v

nexusx-2.0.0/.github/workflows/gh-pages.yml

@@ -0,0 +1,34 @@
+name: GH Pages Deploy
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material mkdocs-static-i18n
+      - run: mkdocs gh-deploy --force

nexusx-2.0.0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI via uv
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Build the package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --token ${{ secrets.PYPI_PUBLISHER }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body: See [CHANGELOG](https://github.com/allmonday/nexusx/blob/master/CHANGELOG.md) for details.
+          generate_release_notes: true
+          files: |
+            dist/*.tar.gz
+            dist/*.whl

nexusx-2.0.0/.gitignore

@@ -0,0 +1,51 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+*.egg
+
+# Virtual environments
+.venv
+venv/
+env/
+ENV/
+
+# Database files
+*.db
+*.sqlite
+*.sqlite3
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# MyPy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Distribution
+*.manifest
+*.spec
+.claude
+
+site

nexusx-2.0.0/.python-version

@@ -0,0 +1 @@
+3.12

nexusx-2.0.0/.skills/README.md

@@ -0,0 +1,127 @@
+# Skills 目录
+
+这个目录包含了可复用的自动化脚本（skills），用于简化常见任务。
+
+## 可用的 Skills
+
+### 📦 release - 版本发布
+
+自动化执行版本发布的标准流程。
+
+#### 使用方法
+
+**Shell 版本（推荐）：**
+```bash
+./.skills/release.sh <version>
+```
+
+**Python 版本：**
+```bash
+python .skills/release.py <version>
+```
+
+**示例：**
+```bash
+./.skills/release.sh 0.8.2
+```
+
+#### 执行步骤
+
+1. ✅ 验证版本号格式（SemVer）
+2. ✅ 检查工作区是否干净
+3. ✅ 更新 `pyproject.toml` 中的版本号
+4. ✅ 运行完整测试套件
+5. ✅ 创建 commit: "bump ver"
+6. ✅ 创建 tag: `v{version}`
+7. ✅ Push tag 到 origin
+
+#### 前置要求
+
+- Git 工作区必须干净（没有未提交的更改）
+- 已安装 `uv` 工具
+- 有 push 到远程仓库的权限
+
+#### 错误处理
+
+- 如果工作区不干净，脚本会中止并提示
+- 如果测试失败，脚本会中止并回滚版本号更改
+- 如果 tag 已存在，脚本会提示使用不同的版本号
+- 如果 push 失败，脚本会提供排查建议
+
+#### 示例输出
+
+```
+============================================================
+📦 Release Version: v0.8.2
+============================================================
+
+🔍 Checking working directory...
+✅ Working directory is clean
+
+📝 Updating version to 0.8.2...
+✅ Updated pyproject.toml to version 0.8.2
+
+🧪 Running tests...
+✅ All tests passed
+
+📝 Creating commit...
+✅ Created commit: abc1234
+
+🏷️  Creating tag...
+✅ Created tag: v0.8.2
+
+🚀 Pushing tag v0.8.2 to origin...
+✅ Tag v0.8.2 pushed to origin
+
+============================================================
+✅ Release completed successfully!
+============================================================
+
+📦 Version: v0.8.2
+📝 Commit: abc1234
+🏷️  Tag: v0.8.2
+🚀 Pushed to: origin/v0.8.2
+
+📋 Recent commits included in this release:
+   abc1234 feat: add new feature
+   def5678 fix: correct bug
+   ghi9012 docs: update documentation
+
+🎉 Done!
+```
+
+## 添加新的 Skill
+
+要添加新的 skill，请遵循以下结构：
+
+```
+.skills/
+├── README.md           # 这个文件
+├── skill-name.md       # Skill 文档
+├── skill-name.sh       # Shell 实现
+└── skill-name.py       # Python 实现（可选）
+```
+
+### Skill 命名规范
+
+- 使用小写字母和连字符
+- 使用动词或动作名称（如 `release`, `deploy`, `test`）
+- 避免使用空格和特殊字符
+
+### 最佳实践
+
+1. **提供清晰的文档**：在 `.md` 文件中说明用法和参数
+2. **错误处理**：验证输入并提供有用的错误消息
+3. **回滚机制**：如果操作失败，尝试回滚更改
+4. **彩色输出**：使用颜色提高可读性
+5. **详细日志**：显示正在执行的步骤
+
+## 在 Claude Code 中使用
+
+你可以要求 Claude Code 执行这些 skills：
+
+```
+请执行版本发布，版本号为 0.8.3
+```
+
+Claude Code 会自动识别并执行相应的 skill 脚本。

nexusx-2.0.0/.skills/release.md

@@ -0,0 +1,73 @@
+# Release Version Skill
+
+发布新版本的标准化流程。
+
+## 使用方法
+
+```bash
+# 发布新版本
+/skill release <version>
+```
+
+例如：
+```bash
+/skill release 0.8.2
+```
+
+## 执行步骤
+
+当用户请求发布新版本时，执行以下步骤：
+
+### 1. 验证版本号
+- 确认版本号格式正确（如 0.8.2, 1.0.0）
+- 检查是否大于当前版本
+
+### 2. 更新版本号
+- 修改 `pyproject.toml` 中的 `version` 字段
+- 使用 Edit tool 更新文件
+
+### 3. 运行测试
+```bash
+uv run pytest
+```
+- 确保所有测试通过
+- 如果测试失败，停止发布流程并报告错误
+
+### 4. 创建 Git Commit
+```bash
+git add pyproject.toml
+git commit -m "bump ver"
+```
+
+### 5. 创建并推送 Tag
+```bash
+git tag v<version>
+git push origin v<version>
+```
+
+### 6. 确认发布
+- 显示发布成功的消息
+- 列出本次发布包含的主要变更（从最近的 commits）
+
+## 注意事项
+
+- 确保工作区干净（没有未提交的更改）
+- 确保 pyproject.toml 文件存在
+- 版本号应该遵循语义化版本规范（SemVer）
+- 如果 push 失败，检查是否有权限或网络问题
+
+## 示例输出
+
+```
+✅ 版本更新成功
+
+📦 版本: v0.8.2
+📝 Commit: abc1234
+🏷️  Tag: v0.8.2
+🚀 已推送到远程仓库
+
+📋 本次发布包含:
+- feat: add new feature
+- fix: correct bug
+- docs: update documentation
+```

nexusx-2.0.0/.skills/release.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+"""Release version skill implementation."""
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+
+def run_command(cmd, check=True, capture_output=True):
+    """Run a shell command and return the result."""
+    result = subprocess.run(
+        cmd,
+        shell=True,
+        capture_output=capture_output,
+        text=True
+    )
+    if check and result.returncode != 0:
+        print(f"❌ Error executing: {cmd}")
+        print(f"   {result.stderr}")
+        sys.exit(1)
+    return result
+
+
+def validate_version(version):
+    """Validate semantic version format."""
+    pattern = r'^\d+\.\d+\.\d+$'
+    if not re.match(pattern, version):
+        print(f"❌ Invalid version format: {version}")
+        print("   Version must follow SemVer (e.g., 0.8.2, 1.0.0)")
+        sys.exit(1)
+    return True
+
+
+def check_working_directory():
+    """Check if working directory is clean."""
+    result = run_command("git status --porcelain")
+    if result.stdout.strip():
+        print("❌ Working directory is not clean")
+        print("   Please commit or stash your changes first")
+        print("\nUncommitted changes:")
+        print(result.stdout)
+        sys.exit(1)
+
+
+def update_pyproject_version(new_version):
+    """Update version in pyproject.toml."""
+    pyproject_path = Path("pyproject.toml")
+    if not pyproject_path.exists():
+        print("❌ pyproject.toml not found")
+        sys.exit(1)
+
+    content = pyproject_path.read_text()
+
+    # Update version line
+    updated = re.sub(
+        r'version\s*=\s*["\']([^"\']+)["\']',
+        f'version = "{new_version}"',
+        content
+    )
+
+    if updated == content:
+        print("❌ Failed to update version in pyproject.toml")
+        sys.exit(1)
+
+    pyproject_path.write_text(updated)
+    print(f"✅ Updated pyproject.toml to version {new_version}")
+
+
+def run_tests():
+    """Run the full test suite."""
+    print("\n🧪 Running tests...")
+    result = run_command("uv run pytest", check=False)
+    if result.returncode != 0:
+        print("❌ Tests failed")
+        print(result.stdout)
+        sys.exit(1)
+    print("✅ All tests passed")
+
+
+def create_commit(version):
+    """Create a commit for version bump."""
+    run_command("git add pyproject.toml uv.lock")
+    run_command('git commit -m "bump ver"')
+    result = run_command("git rev-parse --short HEAD")
+    commit_hash = result.stdout.strip()
+    print(f"✅ Created commit: {commit_hash}")
+    return commit_hash
+
+
+def create_tag(version):
+    """Create a git tag."""
+    tag_name = f"v{version}"
+    result = run_command(f"git tag {tag_name}", check=False)
+    if result.returncode != 0:
+        if "already exists" in result.stderr:
+            print(f"❌ Tag {tag_name} already exists")
+            sys.exit(1)
+        print(f"❌ Failed to create tag: {result.stderr}")
+        sys.exit(1)
+    print(f"✅ Created tag: {tag_name}")
+    return tag_name
+
+
+def push_tag(tag_name):
+    """Push tag to origin."""
+    print(f"\n🚀 Pushing tag {tag_name} to origin...")
+    result = run_command(f"git push origin {tag_name}", check=False)
+    if result.returncode != 0:
+        print("❌ Failed to push tag")
+        print(f"   {result.stderr}")
+        print("\n💡 Tips:")
+        print("   - Check your network connection")
+        print("   - Verify you have push permissions")
+        print(f"   - Try: git push origin {tag_name}")
+        sys.exit(1)
+    print(f"✅ Tag {tag_name} pushed to origin")
+
+
+def get_recent_commits(count=5):
+    """Get recent commit messages."""
+    result = run_command(f"git log --oneline -{count}")
+    return result.stdout.strip().split('\n')
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: release <version>")
+        print("Example: release 0.8.2")
+        sys.exit(1)
+
+    version = sys.argv[1]
+
+    print(f"\n{'='*60}")
+    print(f"📦 Release Version: v{version}")
+    print(f"{'='*60}\n")
+
+    # Step 1: Validate version
+    validate_version(version)
+
+    # Step 2: Check working directory
+    print("🔍 Checking working directory...")
+    check_working_directory()
+    print("✅ Working directory is clean\n")
+
+    # Step 3: Update version in pyproject.toml
+    print(f"📝 Updating version to {version}...")
+    update_pyproject_version(version)
+
+    # Step 4: Run tests
+    run_tests()
+
+    # Step 5: Create commit
+    print("\n📝 Creating commit...")
+    commit_hash = create_commit(version)
+
+    # Step 6: Create tag
+    print("\n🏷️  Creating tag...")
+    tag_name = create_tag(version)
+
+    # Step 7: Push tag
+    push_tag(tag_name)
+
+    # Step 8: Show summary
+    print(f"\n{'='*60}")
+    print("✅ Release completed successfully!")
+    print(f"{'='*60}")
+    print(f"\n📦 Version: {tag_name}")
+    print(f"📝 Commit: {commit_hash}")
+    print(f"🏷️  Tag: {tag_name}")
+    print(f"🚀 Pushed to: origin/{tag_name}")
+
+    print("\n📋 Recent commits included in this release:")
+    for commit in get_recent_commits(3):
+        print(f"   {commit}")
+
+    print("\n🎉 Done!")
+
+
+if __name__ == "__main__":
+    main()

nexusx-2.0.0/.skills/release.sh

@@ -0,0 +1,112 @@
+#!/bin/bash
+# Release version skill - Shell implementation
+
+set -e
+
+# Colors
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Check if version is provided
+if [ -z "$1" ]; then
+    echo -e "${RED}Usage: ./release.sh <version>${NC}"
+    echo "Example: ./release.sh 0.8.2"
+    exit 1
+fi
+
+VERSION=$1
+TAG="v$VERSION"
+
+# Validate version format
+if ! [[ $VERSION =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+    echo -e "${RED}❌ Invalid version format: $VERSION${NC}"
+    echo "   Version must follow SemVer (e.g., 0.8.2, 1.0.0)"
+    exit 1
+fi
+
+echo ""
+echo "============================================================"
+echo -e "${BLUE}📦 Release Version: ${TAG}${NC}"
+echo "============================================================"
+echo ""
+
+# Check working directory
+echo "🔍 Checking working directory..."
+if ! git diff-index --quiet HEAD --; then
+    echo -e "${RED}❌ Working directory is not clean${NC}"
+    echo "   Please commit or stash your changes first"
+    git status --short
+    exit 1
+fi
+echo -e "${GREEN}✅ Working directory is clean${NC}"
+echo ""
+
+# Update version in pyproject.toml
+echo "📝 Updating version to $VERSION..."
+if [ ! -f "pyproject.toml" ]; then
+    echo -e "${RED}❌ pyproject.toml not found${NC}"
+    exit 1
+fi
+
+sed -i.bak "s/^version = .*/version = \"$VERSION\"/" pyproject.toml
+rm -f pyproject.toml.bak
+echo -e "${GREEN}✅ Updated pyproject.toml to version $VERSION${NC}"
+echo ""
+
+# Run tests
+echo "🧪 Running tests..."
+if ! uv run pytest; then
+    echo -e "${RED}❌ Tests failed${NC}"
+    git checkout pyproject.toml
+    exit 1
+fi
+echo -e "${GREEN}✅ All tests passed${NC}"
+echo ""
+
+# Create commit
+echo "📝 Creating commit..."
+git add pyproject.toml uv.lock
+git commit -m "bump ver"
+COMMIT=$(git rev-parse --short HEAD)
+echo -e "${GREEN}✅ Created commit: $COMMIT${NC}"
+echo ""
+
+# Create tag
+echo "🏷️  Creating tag..."
+if git tag $TAG 2>&1 | grep -q "already exists"; then
+    echo -e "${RED}❌ Tag $TAG already exists${NC}"
+    exit 1
+fi
+echo -e "${GREEN}✅ Created tag: $TAG${NC}"
+echo ""
+
+# Push tag
+echo "🚀 Pushing tag $TAG to origin..."
+if ! git push origin $TAG; then
+    echo -e "${RED}❌ Failed to push tag${NC}"
+    echo ""
+    echo "💡 Tips:"
+    echo "   - Check your network connection"
+    echo "   - Verify you have push permissions"
+    echo "   - Try: git push origin $TAG"
+    exit 1
+fi
+echo -e "${GREEN}✅ Tag $TAG pushed to origin${NC}"
+echo ""
+
+# Show summary
+echo "============================================================"
+echo -e "${GREEN}✅ Release completed successfully!${NC}"
+echo "============================================================"
+echo ""
+echo "📦 Version: $TAG"
+echo "📝 Commit: $COMMIT"
+echo "🏷️  Tag: $TAG"
+echo "🚀 Pushed to: origin/$TAG"
+echo ""
+echo "📋 Recent commits included in this release:"
+git log --oneline -3 | sed 's/^/   /'
+echo ""
+echo -e "${GREEN}🎉 Done!${NC}"