create-nevela 0.4.3 → 0.5.1

package/README.md

@@ -1,6 +1,13 @@
 # create-nevela
 
-Create a new [Nevela](https://nevela-docs.vercel.app) app: a Laravel API and a Next.js dashboard, generated from one resource description.
+The `nevela` command. It creates a new [Nevela](https://nevela-docs.vercel.app) app, a Laravel API and a Next.js dashboard generated from one resource description, and runs everything inside one.
+
+```sh
+npm install -g create-nevela    # once
+nevela new my-app
+```
+
+Or without installing anything:
 
 ```sh
 pnpm create nevela my-app
@@ -16,39 +23,35 @@ You need PHP 8.3 or newer, Composer, and Node.js 20 or newer.
 my-app/
 ├─ apps/api/    a Laravel app with Sanctum and Nevela installed
 ├─ apps/web/    the Next.js dashboard, pointed at the API
-└─ nevela       every command, from this folder: php nevela
+└─ nevela       the app's own launcher: php nevela does what nevela does
 ```
 
 Then:
 
 ```sh
 cd my-app
-php nevela dev
+nevela dev
 ```
 
-Open http://localhost:3000/sign-in and sign in as `admin@example.com` with the password `password`. That starter account is in your local database only; add your own with `php artisan nevela:user`.
+Open http://localhost:3000/sign-in and sign in as `admin@example.com` with the password `password`. That starter account is in your local database only; add your own with `nevela user`.
+
+The app starts with an administrator and ten sample users (two editors, eight users), in your local database only, so its Users and Roles screens have something to show. Leave the samples out with `--no-sample-users`.
 
 Add your first resource, from the same folder:
 
 ```sh
-php nevela resource Product --fields="name:string, sku:string!, price:money"
+nevela resource Product --fields="name:string, sku:string!, price:money"
 ```
 
-That writes the Laravel code and the dashboard pages, and creates the table. `php nevela` lists everything else.
+That writes the Laravel code and the dashboard pages, and creates the table. `nevela` on its own lists everything else.
 
-## The nevela command
-
-Install this package once and you have a `nevela` command, in every shell:
-
-```sh
-npm install -g create-nevela
-```
+## Every command
 
 ```sh
 nevela                 # anywhere: everything it can do
 nevela new my-app      # anywhere: create an app (leave the name off and it asks)
 nevela update          # anywhere: update the nevela command itself
-nevela version         # anywhere: the command's version, and the app's when in one
+nevela --version       # anywhere: the command's version, and the app's when in one
 nevela dev             # inside an app: run the API and the dashboard
 nevela upgrade         # inside an app: bring it to the latest Nevela
 ```
@@ -77,7 +80,7 @@ Without the command installed, `npx create-nevela upgrade` does the same, in any
 | `--bundled-package` | Use the copy of `nevela/laravel` inside this installer instead of the release on Packagist. |
 | `-y`, `--yes` | Ask nothing. Only the app name is ever asked for. |
 
-With npm, put options after `--`: `npm create nevela@latest my-app -- --no-install`.
+Through npm's `create`, put options after `--`: `npm create nevela@latest my-app -- --no-install`.
 
 ## How it installs the Laravel package
 

package/index.mjs

@@ -29,6 +29,10 @@ const DOCS = 'https://nevela-docs.vercel.app';
  * The account every new app starts with, so there is something to sign in as straight
  * away. It is created in the app's local database, never in code or a migration, so it
  * does not follow the app to a server.
+ *
+ * It is the app's administrator. Ten sample users are made beside it, with the same
+ * password: two editors and eight users, so the Users screen, the roles and what each
+ * of them is allowed to see have something to show on the first run.
  */
 const ADMIN = { name: 'Admin', email: 'admin@example.com', password: 'password' };
 
@@ -64,19 +68,20 @@ const HELP = `  Create a new Nevela app: a Laravel API and a Next.js dashboard.
     nevela new [name] [options]   Create an app. It asks for the name if you leave it off.
                                   Without the command: pnpm create nevela <name>
     nevela update                 Update the nevela command itself to the latest version
-    nevela version                Which version the nevela command is, and this app when in one
+    nevela --version              Which version the nevela command is, and this app when in one
 
   ${bold('Inside an app')}
     nevela upgrade             Bring this app to the latest Nevela: the package and the dashboard
     nevela dev                 Run the API and the dashboard
     nevela status              Check versions, migrations, users and the dashboard
     nevela resource <Name> --fields="…" [--seed]
-    nevela seed | user | generate | version | migrate | artisan <command>
+    nevela seed | user | generate | migrate | artisan <command>
 
   ${bold('Options')}
     --pm <pnpm|npm|yarn|bun>   Package manager for the dashboard. Default: the one you ran this with.
     --no-install               Don't install the dashboard's dependencies.
-    --no-user                  Don't create the starter admin account.
+    --no-user                  Don't create the starter admin account, or the sample users.
+    --no-sample-users          Create the admin only, without the ten sample users.
     --fast                     Leave out PHPUnit, Pint and Laravel's other development packages.
                                About a third quicker. Add them later: cd apps/api && composer install
     --no-git                   Don't run git init.
@@ -84,7 +89,7 @@ const HELP = `  Create a new Nevela app: a Laravel API and a Next.js dashboard.
                                instead of the release on Packagist.
     -y, --yes                  Ask nothing. (Only the app name is ever asked for.)
     -h, --help                 Show this.
-    -v, --version              Show the version.
+    -v, --version              Show the version. Piped or captured, the number alone.
 
   ${bold('Needs')}  PHP 8.3+, Composer, Node.js 20+
   ${bold('Docs')}   ${DOCS}
@@ -188,7 +193,7 @@ async function step(label, work) {
 }
 
 function parseArgs(argv) {
-  const options = { name: undefined, pm: undefined, install: true, user: true, git: true, yes: false, bundledPackage: false, devTools: true };
+  const options = { name: undefined, pm: undefined, install: true, user: true, samples: true, git: true, yes: false, bundledPackage: false, devTools: true };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === '-h' || arg === '--help') {
@@ -201,6 +206,7 @@ function parseArgs(argv) {
     } else if (arg === '-y' || arg === '--yes') options.yes = true;
     else if (arg === '--no-install') options.install = false;
     else if (arg === '--no-user') options.user = false;
+    else if (arg === '--no-sample-users') options.samples = false;
     else if (arg === '--no-git') options.git = false;
     else if (arg === '--no-dev-tools' || arg === '--fast') options.devTools = false;
     else if (arg === '--bundled-package') options.bundledPackage = true;
@@ -279,7 +285,7 @@ function write(file, contents) {
   fs.writeFileSync(file, contents);
 }
 
-function writeRootFiles(root, { name, title, pm, admin }) {
+function writeRootFiles(root, { name, title, pm, admin, samples }) {
   write(path.join(root, 'package.json'), `${JSON.stringify({
     name,
     version: '0.1.0',
@@ -313,13 +319,15 @@ To check the app at any time (versions, migrations, users, and whether the dashb
 php nevela status
 \`\`\`
 ${admin ? `
-The app starts with one account, in your local database only:
+The app starts with an administrator, in your local database only:
 
 | | |
 |---|---|
 | Email | \`${admin.email}\` |
 | Password | \`${admin.password}\` |
-` : ''}
+${samples ? `
+Ten sample users are there as well, with the same password: two editors and eight users, one of them switched off. They are under **Users** in the dashboard, and what each role may do is under **Roles**. Delete them before real use.
+` : ''}` : ''}
 Everything else runs from this folder too, with \`php nevela\`:
 
 \`\`\`sh
@@ -437,7 +445,10 @@ function appVersion(project) {
   }
 }
 
-/** `nevela version`, from anywhere: the command's version, and the app's when in one. */
+/**
+ * `nevela --version`, from anywhere: the command's version, and the app's when in one.
+ * `nevela version` is the same thing by its older name.
+ */
 function showVersion() {
   const project = findProject(process.cwd());
   const install = installed();
@@ -566,6 +577,13 @@ async function main() {
   if (argv[0] === 'new') argv.shift();
   else if (argv[0] === 'update') return updateTool(argv.slice(1));
   else if (argv[0] === 'version') return showVersion();
+  else if ((argv[0] === '--version' || argv[0] === '-v') && argv.length === 1) {
+    // To a person, the whole answer. To a script (and to `nevela update`, which asks
+    // this of the installed command to check its work), the number and nothing else.
+    if (process.stdout.isTTY) return showVersion();
+    console.log(VERSION);
+    return;
+  }
   else if (COMMANDS.includes(argv[0])) await inProject(argv[0], argv.slice(1));
   else if (argv[0] === 'help' || (startedAsNevela && argv.length === 0)) {
     // `nevela` on its own says what it can do. `pnpm create nevela` on its own starts an
@@ -633,7 +651,7 @@ async function main() {
   // `nevela upgrade` compares against these to tell the files you changed from the ones
   // you didn't, so an update never overwrites your work.
   write(path.join(web, '.nevela.json'), `${JSON.stringify(templateRecord(VERSION), null, 4)}\n`);
-  writeRootFiles(root, { name, title, pm, admin: options.user ? ADMIN : null });
+  writeRootFiles(root, { name, title, pm, admin: options.user ? ADMIN : null, samples: options.user && options.samples });
   const packages = options.install ? start(pm, ['install'], { cwd: web }) : null;
 
   const tokens = await step('Creating the Laravel app', async (progress) => {
@@ -689,13 +707,16 @@ async function main() {
   });
 
   let admin = false;
+  let samples = false;
   await step('Setting up the database', () => {
     // One artisan process for the app key, Sanctum's migration, the generated files, the
-    // migrations and the starter account: each separate call would start Laravel again.
-    const account = options.user && tokens ? [`--name=${ADMIN.name}`, `--email=${ADMIN.email}`, `--password=${ADMIN.password}`] : [];
+    // migrations, the starter account and the sample users: each separate call would
+    // start Laravel again.
+    const account = options.user && tokens ? [`--name=${ADMIN.name}`, `--email=${ADMIN.email}`, `--password=${ADMIN.password}`, ...(options.samples ? [] : ['--no-sample-users'])] : [];
     const setup = run('php', ['artisan', 'nevela:setup', ...account], { cwd: api, allowFailure: true });
     if (setup.ok) {
       admin = account.length > 0;
+      samples = admin && options.samples;
       return;
     }
     // 2: the app is set up and only the starter account could not be created.
@@ -707,7 +728,7 @@ async function main() {
     run('php', ['artisan', 'vendor:publish', '--tag=sanctum-migrations', '--no-interaction'], { cwd: api });
     run('php', ['artisan', 'nevela:generate'], { cwd: api });
     run('php', ['artisan', 'migrate', '--force', '--no-interaction'], { cwd: api });
-    if (account.length) admin = run('php', ['artisan', 'nevela:user', ...account], { cwd: api, allowFailure: true }).ok;
+    if (account.length) admin = run('php', ['artisan', 'nevela:user', ...account.filter((arg) => arg !== '--no-sample-users')], { cwd: api, allowFailure: true }).ok;
   });
 
   let installed = false;
@@ -741,7 +762,10 @@ async function main() {
   if (admin) {
     console.log(`\n    Email      ${bold(ADMIN.email)}`);
     console.log(`    Password   ${bold(ADMIN.password)}\n`);
-    console.log(`  ${dim(`That account is in this app's local database only. Add your own: ${nevela} user`)}`);
+    console.log(`  ${dim(`That account is the administrator, and is in this app's local database only. Add your own: ${nevela} user`)}`);
+    if (samples) {
+      console.log(`  ${dim(`Ten sample users are there too, with the same password: 2 editors and 8 users. See them under Users, and what each may do under Roles.`)}`);
+    }
   }
   console.log(`\n  Add your first resource: ${dim(`${nevela} resource Product --fields="name:string, price:money"`)}`);
   console.log(`  Check the app: ${dim(`${nevela} status`)}   Upgrade it later: ${dim(`${nevela} upgrade`)}   Everything: ${dim(nevela)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nevela",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "description": "Create a new Nevela app: a Laravel API and a Next.js dashboard from one resource description.",
   "type": "module",
   "bin": {

package/template/laravel/README.md

@@ -3,18 +3,20 @@
 The Laravel side of [Nevela](https://nevela-docs.vercel.app): describe a resource once and get its model, migration, validation, policy and REST API, plus the Next.js dashboard screens for it.
 
 ```sh
-php artisan nevela:resource Product --fields="name:string, sku:string!, price:money, kind:enum(stock|digital), notes:text?"
-php artisan migrate
+nevela resource Product --fields="name:string, sku:string!, price:money, kind:enum(stock|digital), notes:text?"
 ```
 
 ## Start a new app
 
-The quickest way is the create command, which sets up Laravel, this package and the dashboard together:
+The quickest way is the `nevela` command, which sets up Laravel, this package and the dashboard together:
 
 ```sh
-pnpm create nevela my-app
+npm install -g create-nevela    # once
+nevela new my-app
 ```
 
+Without installing it, `pnpm create nevela my-app` does the same.
+
 ## Add it to an existing Laravel app
 
 ```sh

package/template/laravel/config/nevela.php

@@ -24,6 +24,18 @@ return [
     'prefix' => 'api',
     'middleware' => ['api', 'auth:sanctum'],
 
+    /*
+    | Permissions of your own, beside the ones every resource gets (products.view,
+    | products.create, products.edit, products.delete) and the built-in users.* and roles.*.
+    | They appear on the dashboard's Roles screen, and you check one anywhere in Laravel
+    | with `$user->can('reports.view')`. Actions are any of: create, view, edit, delete.
+    |
+    |   'permissions' => [
+    |       'reports' => ['name' => 'Reports', 'actions' => ['view']],
+    |   ],
+    */
+    'permissions' => [],
+
     /*
     | Signing in. Every endpoint is under {prefix}/auth. Email and password is always
     | available; the rest can be switched off here. A method that is off is refused by the
@@ -74,8 +86,11 @@ return [
         */
         'attempts_per_address' => 300,
 
-        /* The role a self-registered account starts with. Null leaves the column alone. */
-        'default_role' => null,
+        /*
+        | The role a self-registered account starts with. USER allows nothing beyond the
+        | person's own account, which is what makes open sign-up safe. Null gives no role.
+        */
+        'default_role' => 'USER',
 
         /*
         | Where the dashboard is, for the links in emails and for passkeys, which are tied

package/template/laravel/database/migrations/2026_10_06_000000_create_nevela_access_tables.php

@@ -0,0 +1,79 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+use Illuminate\Support\Str;
+use Nevela\Laravel\Models\Role;
+
+// Roles and permissions, and switching an account off.
+//
+// Until now every signed-in user could do everything. So that upgrading an app changes
+// nothing about who can do what, every user it already has is made an ADMIN here. Give
+// them narrower roles afterwards, from the dashboard's Users screen.
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('nevela_roles', function (Blueprint $table) {
+            $table->uuid('id')->primary();
+            $table->string('name', 80)->unique();
+            $table->string('description', 500)->nullable();
+            // A JSON list of grants: permissions, and patterns such as "products.*".
+            $table->text('grants');
+            // One the app depends on: it can be edited, and not renamed or deleted.
+            $table->boolean('is_system')->default(false);
+            $table->timestamps();
+        });
+
+        Schema::create('nevela_role_user', function (Blueprint $table) {
+            $table->foreignUuid('role_id')->constrained('nevela_roles')->cascadeOnDelete();
+            // A string, so it holds a numeric id or a UUID, whichever the app's users have.
+            $table->string('user_id');
+            $table->primary(['role_id', 'user_id']);
+            $table->index('user_id');
+        });
+
+        $model = config('auth.providers.users.model');
+        $user = is_string($model) && class_exists($model) ? new $model : null;
+        $users = $user?->getTable() ?? 'users';
+        $key = $user?->getKeyName() ?? 'id';
+
+        if (Schema::hasTable($users) && ! Schema::hasColumn($users, 'active')) {
+            Schema::table($users, function (Blueprint $table) {
+                // False: the account can't sign in, and is signed out everywhere.
+                $table->boolean('active')->default(true);
+            });
+        }
+
+        $now = now();
+        $admin = null;
+        foreach (Role::defaults() as $role) {
+            $id = (string) Str::uuid();
+            DB::table('nevela_roles')->insert([
+                'id' => $id,
+                'name' => $role['name'],
+                'description' => $role['description'],
+                'grants' => json_encode($role['grants']),
+                'is_system' => true,
+                'created_at' => $now,
+                'updated_at' => $now,
+            ]);
+            $admin ??= $role['name'] === Role::ADMIN ? $id : null;
+        }
+
+        if ($admin !== null && Schema::hasTable($users)) {
+            DB::table($users)->orderBy($key)->select($key)->chunk(500, function ($rows) use ($admin, $key) {
+                DB::table('nevela_role_user')->insert($rows->map(fn ($row) => ['role_id' => $admin, 'user_id' => (string) $row->{$key}])->all());
+            });
+        }
+    }
+
+    public function down(): void
+    {
+        // The "active" column stays: an app may have had one of its own before this ran.
+        Schema::dropIfExists('nevela_role_user');
+        Schema::dropIfExists('nevela_roles');
+    }
+};

package/template/laravel/src/Access/Access.php

@@ -0,0 +1,168 @@
+<?php
+
+namespace Nevela\Laravel\Access;
+
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+use Nevela\Laravel\Auth\Account;
+use Nevela\Laravel\Models\Role;
+use WeakMap;
+
+/**
+ * Who holds which roles, and what those come to.
+ *
+ * Laravel's gate asks here for any ability shaped like a permission ("products.view"), so
+ * `$user->can('products.view')`, `Gate::authorize('users.edit')` and `@can` all work, and a
+ * generated policy is one line per action.
+ */
+final class Access
+{
+    /** @var WeakMap<object, list<string>>|null Grants per user object, so a request asks the database once. */
+    private static ?WeakMap $grants = null;
+
+    private static bool $ready = false;
+
+    /**
+     * Whether the roles tables exist. Before an upgraded app has run its migrations they
+     * don't, and until then everyone may do everything, as they could before.
+     */
+    public static function ready(): bool
+    {
+        // Only "yes" is remembered: the tables can appear later in the same process.
+        return self::$ready = self::$ready || Schema::hasTable('nevela_roles');
+    }
+
+    /**
+     * The grants a user holds, across all their roles. Patterns are kept as they are:
+     * give the result to Permissions::granted(), and don't compare strings.
+     *
+     * @return list<string>
+     */
+    public static function grantsFor(mixed $user): array
+    {
+        if (! is_object($user)) {
+            return [];
+        }
+        if (! self::ready()) {
+            return ['*'];
+        }
+        self::$grants ??= new WeakMap;
+        if (isset(self::$grants[$user])) {
+            return self::$grants[$user];
+        }
+        if (! self::active($user)) {
+            return self::$grants[$user] = [];
+        }
+
+        $grants = [];
+        foreach (self::rolesOf($user) as $role) {
+            array_push($grants, ...$role->grants);
+        }
+
+        return self::$grants[$user] = array_values(array_unique($grants));
+    }
+
+    public static function allows(mixed $user, string $permission): bool
+    {
+        return Permissions::granted(self::grantsFor($user), $permission);
+    }
+
+    /** An administrator: someone whose roles together come to everything. */
+    public static function isAdmin(mixed $user): bool
+    {
+        return Permissions::hasAll(self::grantsFor($user));
+    }
+
+    /** False when the account has been switched off. An app with no such column has no such thing. */
+    public static function active(mixed $user): bool
+    {
+        $attributes = method_exists($user, 'getAttributes') ? $user->getAttributes() : [];
+
+        // Only an explicit "no" switches an account off: a column with nothing in it doesn't.
+        return ! isset($attributes['active']) || (bool) $attributes['active'];
+    }
+
+    /** @return \Illuminate\Database\Eloquent\Collection<int, Role> */
+    public static function rolesOf(mixed $user)
+    {
+        return Role::query()
+            ->whereIn('id', DB::table('nevela_role_user')->where('user_id', (string) $user->getAuthIdentifier())->select('role_id'))
+            ->orderBy('name')
+            ->get();
+    }
+
+    /**
+     * Replace a user's roles.
+     *
+     * @param  list<string>  $roleIds
+     */
+    public static function assign(mixed $user, array $roleIds): void
+    {
+        $id = (string) $user->getAuthIdentifier();
+        DB::transaction(function () use ($id, $roleIds) {
+            DB::table('nevela_role_user')->where('user_id', $id)->delete();
+            $rows = array_map(fn (string $role) => ['role_id' => $role, 'user_id' => $id], array_values(array_unique($roleIds)));
+            if ($rows !== []) {
+                DB::table('nevela_role_user')->insert($rows);
+            }
+        });
+        self::forget();
+    }
+
+    /** Give a user one role by name, on top of what they have. False when there is no such role. */
+    public static function grant(mixed $user, string $roleName): bool
+    {
+        if (! self::ready()) {
+            return false;
+        }
+        $role = Role::query()->whereRaw('lower(name) = ?', [mb_strtolower($roleName)])->first();
+        if (! $role) {
+            return false;
+        }
+        DB::table('nevela_role_user')->insertOrIgnore(['role_id' => $role->id, 'user_id' => (string) $user->getAuthIdentifier()]);
+        self::forget();
+
+        return true;
+    }
+
+    /**
+     * How many administrators can still sign in, leaving out `$except`.
+     * The last one can't be removed, switched off or given a lesser role.
+     *
+     * Counted here as holding one role that comes to everything (ADMIN, or one like it).
+     * Someone whose lesser roles happen to add up to everything isn't relied on to be the
+     * app's last way in.
+     */
+    public static function otherAdmins(mixed $except = null): int
+    {
+        $model = Account::model();
+        $instance = new $model;
+        $table = $instance->getTable();
+        $key = $instance->getKeyName();
+        $hasActive = Schema::hasColumn($table, 'active');
+
+        $all =Role::query()->get()->filter(fn (Role $role) => Permissions::hasAll($role->grants))->pluck('id')->all();
+        $ids = DB::table('nevela_role_user')->whereIn('role_id', $all)->distinct()->pluck('user_id')->all();
+        if ($except !== null) {
+            $ids = array_values(array_diff($ids, [(string) $except->getAuthIdentifier()]));
+        }
+        if ($ids === []) {
+            return 0;
+        }
+
+        return $model::query()->whereIn($key, $ids)->when($hasActive, fn ($query) => $query->where('active', true))->count();
+    }
+
+    /** Forget what has been worked out, after roles or who holds them change. */
+    public static function forget(): void
+    {
+        self::$grants = null;
+    }
+
+    /** For tests that build and drop the tables within one process. */
+    public static function reset(): void
+    {
+        self::$grants = null;
+        self::$ready = false;
+    }
+}