roo

.roo/rules/blender.md

@@ -0,0 +1,90 @@
+# Roo Code rules — enforce extensions (no legacy) and auto-migrate if detected
+
+## 1. Hard mode: never run legacy
+
+- Disallow any pipeline using `bl_info` packaging/installation.
+- If no `blender_manifest.toml` exists, create it (see §3) and proceed as an **Extension** only.
+- If both `bl_info` and `blender_manifest.toml` exist, ignore `bl_info`. Fail if any legacy pack/install step is attempted.
+
+## 2. Detection and fail-fast
+
+Treat as **legacy** if:
+
+- Missing `blender_manifest.toml`, **or**
+- Absolute intra-package imports (e.g., `import my_addon.module`), **or**
+- External deps not vendored as wheels in `./wheels/`.
+
+On detection → run §4 (migration). If migration can’t complete, fail with an actionable diff.
+
+## 3. Required extension scaffold (write/update)
+
+Create `blender_manifest.toml` at repo root:
+
+```toml
+schema_version = "1.0.0"
+id = "<package_name>"           # must equal the top-level package folder
+version = "1.0.0"
+name = "<Human Name>"
+type = "add-on"
+maintainer = "<Name> <email@example.com>"
+blender_version_min = "4.2.0"
+license = "GPL-3.0-or-later"
+```
+
+Rules:
+
+- Single top-level Python package whose folder **equals** `id`.
+- `AddonPreferences` live in the root package and must be visible via Extensions.
+
+## 4. Auto-migration (legacy → extension)
+
+1. Move metadata from `bl_info` → `blender_manifest.toml`; **remove** `bl_info`.
+2. Convert absolute intra-package imports to **relative** (`from . import x`).
+3. Vendor Python deps as wheels under `./wheels/` (platform-specific if needed).
+4. Enforce layout:
+
+```
+<repo>/
+├─ <id>/                # Python package
+│  └─ __init__.py
+├─ blender_manifest.toml
+└─ wheels/              # optional, *.whl
+```
+
+5. Build only an **Extension** zip.
+
+## 5. Build and install (extensions only)
+
+- Use Blender’s Extension Builder/CLI to produce `id-version.zip`.
+- Prohibit legacy zipping of parent directories.
+- Install-test on a **clean** profile: Preferences → Extensions → Install from Disk; enable/disable must pass.
+
+## 6. CI guardrails
+
+- Lint manifest (keys, semver; `id == package folder`).
+- Assert **no** `bl_info` remains.
+- Block absolute intra-package imports.
+- Verify wheels exist for any bundled deps.
+- Headless smoke test: register → basic op → unregister without errors.
+
+## 7. Preferences guarantee
+
+- Define `bpy.types.AddonPreferences` in the root package with `bl_idname = __package__`.
+- Must appear under **Edit → Preferences → Add-ons → [Your Add-on]**.
+- Access pattern:
+
+```python
+prefs = bpy.context.preferences.addons[__package__].preferences
+```
+
+## 8. Failure messages (actionable)
+
+- `Legacy detected: manifest created, imports converted, bl_info removed. Re-run build.`
+- `Extension layout invalid: 'id' must equal package folder.`
+- `Missing wheels: dependency X referenced but no wheel under ./wheels/.`
+
+## 9. Explicitly blocked
+
+- No dual artifacts (legacy + extension) from the same commit.
+- No network installs or `pip` at runtime.
+- Artifacts must be self-contained.