Text-Texture-Generator-for-Blender/.roo/rules/blender.md

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:

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:

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.