create-nevela 0.4.2 → 0.5.0

package/README.md

@@ -28,6 +28,8 @@ php 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`.
 
+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

package/index.mjs

@@ -6,7 +6,7 @@
 //
 // No dependencies on purpose: this runs before anything is installed.
 
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -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' };
 
@@ -76,7 +80,8 @@ const HELP = `  Create a new Nevela app: a Laravel API and a Next.js dashboard.
   ${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.
@@ -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
@@ -369,17 +377,62 @@ async function inProject(name, args) {
   process.exit(status);
 }
 
+/**
+ * How the copy that is running was installed, or null when it isn't the installed command.
+ * The folder it was started through is passed as well as the one its files are in: under
+ * pnpm 11 only the first says it is pnpm's.
+ */
+function installed() {
+  if (fromRepository) return null;
+  const startedFrom = process.argv[1] ? path.dirname(path.resolve(process.argv[1])) : here;
+  return globalInstall(here, fs.existsSync, startedFrom);
+}
+
+/** What typing `nevela` runs now, as "x.y.z", or null when that can't be found out. */
+function versionOnPath() {
+  const answer = spawnCommand('nevela', ['--version'], { stdio: 'pipe', encoding: 'utf8' });
+  return /^\d+\.\d+\.\d+$/m.exec(`${answer.stdout ?? ''}`)?.[0] ?? null;
+}
+
+/** The launcher of the nevela command in `dir`: the file the shell runs. */
+const launcherIn = (dir) => path.join(dir, windows ? 'nevela.cmd' : 'nevela');
+
+/** The version of the nevela command in `dir`, as "x.y.z", or null when it won't say. */
+function copyVersion(dir) {
+  const file = launcherIn(dir);
+  const answer = windows
+    ? spawnSync(`"${file}" --version`, { shell: true, stdio: 'pipe', encoding: 'utf8' })
+    : spawnSync(file, ['--version'], { stdio: 'pipe', encoding: 'utf8' });
+  return /^\d+\.\d+\.\d+$/m.exec(`${answer.stdout ?? ''}`)?.[0] ?? null;
+}
+
 /**
  * Say so when the nevela command is installed more than once. Only the first on the PATH
  * ever runs, so an update to one of the others looks like an update that did nothing.
+ * The one to keep is the newest, which is not always the one that runs.
  */
 function otherCopies() {
-  const copies = copiesOnPath();
+  const copies = copiesOnPath().map((dir) => ({ dir, version: copyVersion(dir) }));
   if (copies.length < 2) return;
+  let keep = copies[0];
+  for (const copy of copies) {
+    if (copy.version && (!keep.version || isNewer(copy.version, keep.version))) keep = copy;
+  }
+  const width = Math.max(...copies.map((copy) => copy.dir.length));
   console.log(`\n  ${red('!')} The nevela command is installed ${copies.length} times. Typing ${bold('nevela')} runs the first of these:`);
-  for (const dir of copies) console.log(`      ${dir}`);
-  console.log(`    Keep that one and remove the rest, so there is one to keep up to date:`);
-  for (const dir of copies.slice(1)) console.log(`      ${bold(removeCommand(dir))}`);
+  for (const copy of copies) console.log(`      ${copy.dir.padEnd(width)}  ${copy.version ? `v${copy.version}` : ''}`);
+  console.log(keep === copies[0]
+    ? `    Keep that one and remove the rest, so there is one to keep up to date:`
+    : `    The one that runs is not the newest. Remove the others, and ${bold(`v${keep.version}`)} is what ${bold('nevela')} runs:`);
+  const launcher = (dir) => {
+    try {
+      return fs.readFileSync(launcherIn(dir), 'utf8').slice(0, 4000);
+    } catch {
+      return '';
+    }
+  };
+  const removals = new Set(copies.filter((copy) => copy !== keep).map((copy) => removeCommand(copy.dir, launcher(copy.dir))));
+  for (const removal of removals) console.log(`      ${bold(removal)}`);
 }
 
 /** The version of Nevela an app has installed, read from the package, or null. */
@@ -395,7 +448,7 @@ function appVersion(project) {
 /** `nevela version`, from anywhere: the command's version, and the app's when in one. */
 function showVersion() {
   const project = findProject(process.cwd());
-  const install = fromRepository ? null : globalInstall(here);
+  const install = installed();
   console.log(`\n  ${indigo(bold('Nevela command'))}   ${bold(`v${VERSION}`)}${install ? `  ${dim(`installed with ${install.manager}`)}` : ''}`);
   if (project) {
     const app = appVersion(project);
@@ -459,7 +512,7 @@ async function askName() {
  */
 async function updateTool(args) {
   const project = findProject(process.cwd());
-  const install = fromRepository ? null : globalInstall(here);
+  const install = installed();
 
   if (!install) {
     // Run through npx or `pnpm dlx`, which fetch the latest every time, started by an
@@ -485,18 +538,29 @@ async function updateTool(args) {
   if (latest === null) {
     // Not the same as being up to date, so it isn't reported as that.
     console.log(`  ${red('!')} Couldn't reach npm to see whether there is a newer nevela than ${bold(VERSION)}. Nothing was changed.`);
-    console.log(`    Try again when you are online, or run:  ${install.command.join(' ')}`);
+    console.log(`    Try again when you are online, or run:  ${install.command().join(' ')}`);
     process.exitCode = 1;
   } else if (!newer) {
     console.log(`  ${green(`✔ Already on the latest version (v${VERSION}). Nothing to do.`)}`);
   } else {
-    console.log(`  Updating v${VERSION} → ${bold(`v${newer}`)} ${dim(`(${install.command.join(' ')})`)}\n`);
-    const [command, ...rest] = install.command;
+    // The version by number, not "latest": pnpm holds "latest" back for a day.
+    const [command, ...rest] = install.command(newer);
+    console.log(`  Updating v${VERSION} → ${bold(`v${newer}`)} ${dim(`(${[command, ...rest].join(' ')})`)}\n`);
     const result = spawnCommand(command, rest, { stdio: 'inherit' });
     if (result.error || result.status !== 0) {
-      fail(`Couldn't update the nevela command.`, `Run it yourself to see why:  ${install.command.join(' ')}`);
+      fail(`Couldn't update the nevela command.`, `Run it yourself to see why:  ${[command, ...rest].join(' ')}`);
+    }
+    // The package manager saying so isn't the same as the command being newer: ask it.
+    const now = versionOnPath();
+    if (now === newer || now === null) {
+      console.log(`\n  ${green(`✔ Updated to v${newer}.`)} ${dim('Every nevela command, and every app you create from now on, uses it.')}`);
+    } else {
+      console.log(`\n  ${red('!')} ${install.manager} installed ${bold(`v${newer}`)}, but typing ${bold('nevela')} still runs ${bold(`v${now}`)}.`);
+      if (copiesOnPath().length < 2) {
+        console.log(`    Open a new terminal and run ${bold('nevela version')}. If it still says v${now}, the copy that runs was installed another way.`);
+      }
+      process.exitCode = 1;
     }
-    console.log(`\n  ${green(`✔ Updated to v${newer}.`)} ${dim('Every nevela command, and every app you create from now on, uses it.')}`);
   }
   otherCopies();
   if (project) {
@@ -577,7 +641,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) => {
@@ -633,13 +697,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.
@@ -651,7 +718,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;
@@ -685,7 +752,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.2",
+  "version": "0.5.0",
   "description": "Create a new Nevela app: a Laravel API and a Next.js dashboard from one resource description.",
   "type": "module",
   "bin": {

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;
+    }
+}