role-craft: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this package is

i74ifa/role-craft is a Laravel package that auto-generates spatie/laravel-permission permissions (and a default role) from Eloquent models found under app/Models/. It ships two artisan commands and a small set of helpers — no runtime services. PHP 8.4+, Laravel 12/13, Spatie Permission 7+.

Distributed as a Composer library; consumers composer require i74ifa/role-craft and optionally php artisan vendor:publish --tag=role-craft-config.

Commands

composer test                       # vendor/bin/phpunit (all suites)
composer test-coverage              # HTML coverage report → ./coverage
vendor/bin/phpunit --testsuite Unit
vendor/bin/phpunit --testsuite Feature
vendor/bin/phpunit --filter ModelHelperExclusionTest          # one class
vendor/bin/phpunit --filter test_wildcard_matches_subdirectory  # one method

There is no lint/format step configured. The test bootstrap uses an in-memory SQLite database via Orchestra Testbench — no external DB needed.

Architecture

The package is intentionally tiny. The "big picture" is in three files:

• src/RoleCraftServiceProvider.php — registers the two artisan commands and publishes config under tag role-craft-config. Uses mergeConfigFrom, so new config keys ship as safe defaults without forcing a republish.
• src/Console/Commands/RoleCraftCommand.php (role-craft:generate) — the bootstrapper. Resolves the role (creates if missing), resolves the model list (--models=... shorthand or ModelHelper::getAll()), then for each model × each action creates the permission if missing. Gotcha: it calls $role->syncPermissions($createdPermissions) with the newly created permissions only — a second run with nothing new effectively empties the role. Treat generate as a one-shot bootstrap; use role-craft:sync for idempotent role assignment.
• src/Console/Commands/RoleCraftSyncCommand.php (role-craft:sync) — the idempotent assignment tool. --all short-circuits to Permission::all(). Without it, the same model-resolution path is used (--models= or directory scan).