neroued-3mf 0.2.0__tar.gz

neroued_3mf-0.2.0/.clang-format

@@ -0,0 +1,17 @@
+BasedOnStyle: LLVM
+IndentWidth: 4
+ColumnLimit: 100
+AllowShortFunctionsOnASingleLine: Inline
+AllowShortIfStatementsOnASingleLine: AllIfsAndElse
+AllowShortLoopsOnASingleLine: true
+AllowShortBlocksOnASingleLine: Always
+BreakBeforeBraces: Attach
+SortIncludes: CaseInsensitive
+IncludeBlocks: Regroup
+IncludeCategories:
+  - Regex: '^"neroued/'
+    Priority: 1
+  - Regex: '^"'
+    Priority: 2
+  - Regex: '^<'
+    Priority: 3

neroued_3mf-0.2.0/.cursor/hooks/block-dangerous.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# beforeShellExecution hook: block destructive commands
+
+input=$(cat)
+command=$(echo "$input" | python3 -c "import sys,json; print(json.load(sys.stdin).get('command',''))" 2>/dev/null)
+
+[ -z "$command" ] && { echo '{"permission":"allow"}'; exit 0; }
+
+deny_with() {
+    cat <<EOF
+{"permission":"deny","user_message":"$1","agent_message":"$1 请使用更安全的替代方案。"}
+EOF
+    exit 0
+}
+
+ask_with() {
+    cat <<EOF
+{"permission":"ask","user_message":"$1"}
+EOF
+    exit 0
+}
+
+# --- hard block ---
+
+if echo "$command" | grep -qE 'rm\s+(-[^ ]*)?r[^ ]*f[^ ]*\s+/\s*$|rm\s+(-[^ ]*)?r[^ ]*f[^ ]*\s+/\*'; then
+    deny_with "已拦截：递归删除根文件系统"
+fi
+
+if echo "$command" | grep -qE 'git\s+push\s+.*--force.*\s+(origin\s+)?(master|main)\b|git\s+push\s+-f\s+.*\s+(origin\s+)?(master|main)\b'; then
+    deny_with "已拦截：禁止 force push 到 master/main"
+fi
+
+if echo "$command" | grep -qE 'mkfs\.|>\s*/dev/sd|:\(\)\{|fork\s*bomb'; then
+    deny_with "已拦截：潜在的破坏性系统命令"
+fi
+
+if echo "$command" | grep -qE 'dd\s+.*of=/dev/sd'; then
+    deny_with "已拦截：直接写入块设备"
+fi
+
+# --- ask confirmation ---
+
+if echo "$command" | grep -qE 'git\s+reset\s+--hard'; then
+    ask_with "git reset --hard 将丢弃所有未提交的更改，是否继续？"
+fi
+
+if echo "$command" | grep -qE 'git\s+clean\s+-[^ ]*f'; then
+    ask_with "git clean -f 将删除未跟踪的文件，是否继续？"
+fi
+
+echo '{"permission":"allow"}'
+exit 0

neroued_3mf-0.2.0/.cursor/hooks/check-docs-sync.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# stop hook: remind to sync docs when API/build files changed but docs weren't
+
+input=$(cat)
+status=$(echo "$input" | python3 -c "import sys,json; print(json.load(sys.stdin).get('status',''))" 2>/dev/null)
+
+[ "$status" != "completed" ] && { echo '{}'; exit 0; }
+
+project_dir="${CURSOR_PROJECT_DIR:-$(pwd)}"
+cd "$project_dir" || { echo '{}'; exit 0; }
+
+changed=$(git diff --name-only HEAD 2>/dev/null; git diff --cached --name-only 2>/dev/null)
+[ -z "$changed" ] && { echo '{}'; exit 0; }
+
+needs_docs=false
+
+if echo "$changed" | grep -qE '(include/.*\.(h|hpp))'; then
+    needs_docs=true
+fi
+if echo "$changed" | grep -qE '(src/.*\.(cpp|h|hpp))'; then
+    needs_docs=true
+fi
+if echo "$changed" | grep -qE '(CMakeLists\.txt|cmake/)'; then
+    needs_docs=true
+fi
+
+if [ "$needs_docs" = false ]; then
+    echo '{}'
+    exit 0
+fi
+
+docs_updated=false
+if echo "$changed" | grep -qE '(^docs/|^README\.md|^AGENTS\.md)'; then
+    docs_updated=true
+fi
+
+if [ "$docs_updated" = false ]; then
+    cat <<'EOF'
+{"followup_message":"检测到公共头文件、实现代码或构建配置有变更，但 docs/ 和 README.md 未同步更新。请检查是否需要更新文档（参考 .cursor/rules/sync-docs.mdc 中的触发条件）。如果本次变更不涉及用户可见 API 或构建选项，可以忽略此提醒。"}
+EOF
+else
+    echo '{}'
+fi
+
+exit 0

neroued_3mf-0.2.0/.cursor/hooks/format-cpp.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+# afterFileEdit hook: auto-format C++ files with clang-format
+
+input=$(cat)
+file_path=$(echo "$input" | python3 -c "import sys,json; print(json.load(sys.stdin).get('file_path',''))" 2>/dev/null)
+
+[ -z "$file_path" ] && exit 0
+[ ! -f "$file_path" ] && exit 0
+
+case "$file_path" in
+    *.cpp|*.h|*.hpp|*.cc|*.cxx)
+        if command -v clang-format &>/dev/null; then
+            clang-format -i "$file_path" 2>/dev/null
+        fi
+        ;;
+esac
+
+exit 0

neroued_3mf-0.2.0/.cursor/hooks/protect-secrets.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# beforeReadFile hook: block reading sensitive files
+
+input=$(cat)
+file_path=$(echo "$input" | python3 -c "import sys,json; print(json.load(sys.stdin).get('file_path',''))" 2>/dev/null)
+
+[ -z "$file_path" ] && { echo '{"permission":"allow"}'; exit 0; }
+
+filename=$(basename "$file_path")
+
+deny_with() {
+    cat <<EOF
+{"permission":"deny","user_message":"已阻止读取敏感文件: $filename — $1"}
+EOF
+    exit 0
+}
+
+case "$filename" in
+    .env|.env.local|.env.production|.env.staging)
+        deny_with "环境变量文件可能包含密钥"
+        ;;
+    .env.*.local)
+        deny_with "本地环境变量文件可能包含密钥"
+        ;;
+    credentials.json|service-account*.json)
+        deny_with "凭据文件"
+        ;;
+    id_rsa|id_ed25519|id_ecdsa|*.pem)
+        deny_with "私钥文件"
+        ;;
+    .git-credentials|.netrc)
+        deny_with "Git 凭据文件"
+        ;;
+esac
+
+case "$file_path" in
+    */.ssh/*)
+        deny_with "SSH 目录中的文件"
+        ;;
+esac
+
+echo '{"permission":"allow"}'
+exit 0

neroued_3mf-0.2.0/.cursor/hooks.json

@@ -0,0 +1,29 @@
+{
+  "version": 1,
+  "hooks": {
+    "afterFileEdit": [
+      {
+        "command": ".cursor/hooks/format-cpp.sh"
+      }
+    ],
+    "beforeShellExecution": [
+      {
+        "command": ".cursor/hooks/block-dangerous.sh",
+        "timeout": 5
+      }
+    ],
+    "beforeReadFile": [
+      {
+        "command": ".cursor/hooks/protect-secrets.sh",
+        "timeout": 5
+      }
+    ],
+    "stop": [
+      {
+        "command": ".cursor/hooks/check-docs-sync.sh",
+        "timeout": 15,
+        "loop_limit": 1
+      }
+    ]
+  }
+}

neroued_3mf-0.2.0/.cursor/rules/code-structure.mdc

@@ -0,0 +1,25 @@
+---
+description: 工具函数复用与实现结构规范
+globs: "**/*.cpp,**/*.h"
+alwaysApply: true
+---
+
+# 工具函数复用与实现结构
+
+## 工具函数复用
+
+- 禁止重复编写语义相同的工具函数。
+- 新增工具函数前，先检索项目内是否已有可复用实现。
+- 跨模块复用的函数应放入 `src/internal/` 目录下的内部头文件。
+- 仅当前文件使用的工具函数应保留为匿名命名空间局部实现。
+
+## .cpp 文件结构
+
+- 避免在 .cpp 内做非必要前向声明；优先通过合理的函数定义顺序解决依赖。
+- 实现文件应按"工具函数 → 核心流程 → 对外接口"组织。
+
+## 命名空间约定
+
+- 公共 API 使用 `neroued_3mf` 命名空间。
+- 内部实现使用 `neroued_3mf::detail` 命名空间。
+- 公共头文件位于 `include/neroued/3mf/`，内部头文件位于 `src/` 及 `src/internal/`。

neroued_3mf-0.2.0/.cursor/rules/cpp-formatting.mdc

@@ -0,0 +1,17 @@
+---
+description: C++ 代码格式化规范
+globs: "**/*.cpp,**/*.h,**/*.hpp,**/*.cc,**/*.cxx"
+alwaysApply: true
+---
+
+# C++ 代码格式化
+
+每次修改 `.cpp`、`.h`、`.hpp`、`.cc`、`.cxx` 文件后，必须使用项目根目录的 `.clang-format` 配置对修改的文件运行格式化：
+
+```bash
+clang-format -i <modified-files>
+```
+
+- 仅对本次修改过的文件执行，不要全量格式化
+- 在所有编辑完成后统一执行一次即可，无需每次编辑后都执行
+- 格式化风格基于 LLVM，缩进 4 空格，列宽限制 100

neroued_3mf-0.2.0/.cursor/rules/cross-platform-cpp.mdc

@@ -0,0 +1,27 @@
+---
+description: C++ 跨平台编译规范
+globs: "**/*.cpp,**/*.h,**/*.hpp,**/CMakeLists.txt,**/*.cmake"
+alwaysApply: false
+---
+
+# C++ 跨平台编译规范
+
+## 文件系统路径
+
+禁止硬编码 POSIX 路径，一律使用 `std::filesystem`（C++17）。
+
+## 随机数 / ID 生成
+
+禁止直接读取 `/dev/urandom`，使用 `std::random_device`。
+
+## CMake 外部库链接
+
+禁止硬编码 Linux 特有的库名，使用 find_package 或条件分支。
+
+## 平台宏判断
+
+需要平台差异时，使用标准宏：`_WIN32`、`__APPLE__`。
+
+## 变更检查
+
+每次新增系统调用或文件操作时，必须确认跨平台兼容性。

neroued_3mf-0.2.0/.cursor/rules/git-policy.mdc

@@ -0,0 +1,11 @@
+---
+description: Git 提交与合并规范
+globs: "**/*"
+alwaysApply: true
+---
+
+# Git 提交与合并规范
+
+- 禁止在 master/main 分支直接提交代码并推送。
+- 所有代码改动必须在独立分支完成，并通过 Pull Request 合并。
+- 分支命名：feat/<topic>、fix/<topic>、refactor/<topic>、docs/<topic>、chore/<topic>

neroued_3mf-0.2.0/.cursor/rules/sync-docs.mdc

@@ -0,0 +1,17 @@
+---
+description: 文档同步规范
+globs: "**/*"
+alwaysApply: true
+---
+
+# 文档同步
+
+当修改涉及以下内容时，检查对应文档是否需要同步更新：
+
+- 公共 API 变更（头文件增删、函数签名变化）→ `docs/API.md`、`AGENTS.md`
+- Document 模型变更（字段增删、校验规则变化）→ `docs/DESIGN.md`
+- 配置参数增删（WriteOptions 等）→ `docs/BUILDING.md`
+- 构建选项变化（CMake 选项、依赖变化）→ `docs/BUILDING.md`
+- 用法示例变更 → `docs/EXAMPLES.md`
+- 仓库结构变化（新增/删除/重命名文件或目录）→ `AGENTS.md`
+- 核心亮点或定位变更 → `README.md`

neroued_3mf-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,230 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+env:
+  WIN_VCPKG_ROOT: C:/vcpkg
+  WIN_VCPKG_TRIPLET: x64-windows
+
+jobs:
+  # ── C++ format check (changed files only) ─────────────────────────────────
+  format-check:
+    name: clang-format
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install clang-format-18
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends clang-format-18
+
+      - name: Check formatting of changed files
+        run: |
+          BASE="${{ github.event.pull_request.base.sha }}"
+          FILES=$(git diff --name-only --diff-filter=ACM "$BASE" HEAD \
+            | grep -E '\.(cpp|h|hpp|cc|cxx)$' \
+            | grep -E '^(src|include|python|tests)/' || true)
+
+          if [ -z "$FILES" ]; then
+            echo "No C++ files changed, skipping."
+            exit 0
+          fi
+
+          echo "Checking formatting for:"
+          echo "$FILES"
+          FAILED=0
+          for f in $FILES; do
+            if ! clang-format-18 --dry-run --Werror "$f" 2>/dev/null; then
+              echo "::error file=$f::Format mismatch. Run: clang-format -i $f"
+              FAILED=1
+            fi
+          done
+
+          if [ "$FAILED" -eq 1 ]; then
+            echo "::error::Some files need formatting."
+            exit 1
+          fi
+          echo "All changed C++ files are correctly formatted."
+
+  # ── C++ build & test ──────────────────────────────────────────────────────
+  cpp-build:
+    name: C++ (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-22.04, macos-14, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      # ── Linux ─────────────────────────────────────────────────────────────
+      - name: Install dependencies (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends zlib1g-dev ninja-build ccache
+          mkdir -p ~/.cache/ccache
+
+      - name: Cache ccache (Linux)
+        if: runner.os == 'Linux'
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ccache
+          key: ccache-linux-${{ hashFiles('CMakeLists.txt') }}
+          restore-keys: ccache-linux-
+
+      - name: Configure (Linux)
+        if: runner.os == 'Linux'
+        env:
+          CMAKE_C_COMPILER_LAUNCHER: ccache
+          CMAKE_CXX_COMPILER_LAUNCHER: ccache
+        run: |
+          ccache --set-config=max_size=500M
+          ccache -z
+          cmake -S . -B build -G Ninja \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DN3MF_BUILD_TESTS=ON
+
+      # ── macOS ─────────────────────────────────────────────────────────────
+      - name: Install dependencies (macOS)
+        if: runner.os == 'macOS'
+        run: brew install ninja ccache libomp
+
+      - name: Cache ccache (macOS)
+        if: runner.os == 'macOS'
+        uses: actions/cache@v4
+        with:
+          path: ~/Library/Caches/ccache
+          key: ccache-macos-${{ hashFiles('CMakeLists.txt') }}
+          restore-keys: ccache-macos-
+
+      - name: Configure (macOS)
+        if: runner.os == 'macOS'
+        env:
+          CMAKE_C_COMPILER_LAUNCHER: ccache
+          CMAKE_CXX_COMPILER_LAUNCHER: ccache
+        run: |
+          ccache --set-config=max_size=500M
+          ccache -z
+          cmake -S . -B build -G Ninja \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DN3MF_BUILD_TESTS=ON \
+            -DOpenMP_ROOT=$(brew --prefix libomp)
+
+      # ── Windows ───────────────────────────────────────────────────────────
+      - name: Cache vcpkg packages (Windows)
+        if: runner.os == 'Windows'
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.WIN_VCPKG_ROOT }}/installed
+          key: vcpkg-win-zlib-${{ runner.os }}
+          restore-keys: vcpkg-win-zlib-
+
+      - name: Install dependencies (Windows)
+        if: runner.os == 'Windows'
+        run: vcpkg install zlib:${{ env.WIN_VCPKG_TRIPLET }}
+
+      - uses: ilammy/msvc-dev-cmd@v1
+        if: runner.os == 'Windows'
+
+      - name: Configure (Windows)
+        if: runner.os == 'Windows'
+        run: >
+          cmake -S . -B build -G Ninja
+          -DCMAKE_TOOLCHAIN_FILE="${{ env.WIN_VCPKG_ROOT }}/scripts/buildsystems/vcpkg.cmake"
+          -DVCPKG_TARGET_TRIPLET=${{ env.WIN_VCPKG_TRIPLET }}
+          -DCMAKE_BUILD_TYPE=Release
+          -DN3MF_BUILD_TESTS=ON
+
+      # ── Build & test ──────────────────────────────────────────────────────
+      - name: Build
+        run: cmake --build build --config Release -j4
+
+      - name: Test
+        run: ctest --test-dir build --build-config Release --output-on-failure
+
+      - name: ccache stats
+        if: always() && runner.os != 'Windows'
+        run: ccache -s
+
+  # ── Python bindings build & test ──────────────────────────────────────────
+  python-test:
+    name: Python ${{ matrix.python-version }} (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-22.04, macos-14, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install system dependencies (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends zlib1g-dev
+
+      - name: Install system dependencies (macOS)
+        if: runner.os == 'macOS'
+        run: brew install libomp
+
+      - name: Cache vcpkg packages (Windows)
+        if: runner.os == 'Windows'
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.WIN_VCPKG_ROOT }}/installed
+          key: vcpkg-win-zlib-${{ runner.os }}
+          restore-keys: vcpkg-win-zlib-
+
+      - name: Install system dependencies (Windows)
+        if: runner.os == 'Windows'
+        run: vcpkg install zlib:${{ env.WIN_VCPKG_TRIPLET }}
+
+      - uses: ilammy/msvc-dev-cmd@v1
+        if: runner.os == 'Windows'
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package (Linux)
+        if: runner.os == 'Linux'
+        run: pip install --verbose .
+
+      - name: Install package (macOS)
+        if: runner.os == 'macOS'
+        run: |
+          export SKBUILD_CMAKE_DEFINE="OpenMP_ROOT=$(brew --prefix libomp)"
+          pip install --verbose .
+
+      - name: Install package (Windows)
+        if: runner.os == 'Windows'
+        run: pip install --verbose .
+        env:
+          CMAKE_TOOLCHAIN_FILE: ${{ env.WIN_VCPKG_ROOT }}/scripts/buildsystems/vcpkg.cmake
+          SKBUILD_CMAKE_DEFINE: "VCPKG_TARGET_TRIPLET=${{ env.WIN_VCPKG_TRIPLET }}"
+
+      - name: Run tests
+        run: |
+          pip install pytest
+          pytest python/tests -v
+        env:
+          N3MF_DLL_DIR: ${{ runner.os == 'Windows' && format('{0}/installed/{1}/bin', env.WIN_VCPKG_ROOT, env.WIN_VCPKG_TRIPLET) || '' }}