create-nevela 0.1.2 → 0.1.3

package/README.md

@@ -16,14 +16,14 @@ 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
-└─ scripts/     `dev` runs both together
+└─ nevela       every command, from this folder: php nevela
 ```
 
 Then:
 
 ```sh
 cd my-app
-pnpm run dev
+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`.

package/index.mjs

@@ -227,7 +227,7 @@ function writeRootFiles(root, { name, title, pm, admin }) {
     private: true,
     type: 'module',
     scripts: {
-      dev: 'node scripts/dev.mjs',
+      dev: 'php nevela dev',
       nevela: 'php nevela',
       'dev:api': 'cd apps/api && php artisan serve',
       'dev:web': `cd apps/web && ${pm} run dev`,
@@ -236,50 +236,6 @@ function writeRootFiles(root, { name, title, pm, admin }) {
 
   write(path.join(root, '.gitignore'), 'node_modules/\nvendor/\n.env\n.env.*\n!.env.example\n.next/\n*.tsbuildinfo\nnext-env.d.ts\n');
 
-  write(path.join(root, 'scripts', 'dev.mjs'), `// Run the Laravel API and the Next.js dashboard together: \`${pm} run dev\`.
-import { spawn } from 'node:child_process';
-
-const shell = process.platform === 'win32';
-const apps = [
-  { name: 'api', colour: 35, command: 'php', args: ['artisan', 'serve'], cwd: 'apps/api' },
-  { name: 'web', colour: 36, command: '${pm}', args: ['run', 'dev'], cwd: 'apps/web' },
-];
-
-const running = apps.map(({ name, colour, command, args, cwd }) => {
-  // One string when going through a shell: Node warns about (and doesn't escape) separate args there.
-  const child = shell
-    ? spawn([command, ...args].join(' '), { cwd, shell, stdio: ['ignore', 'pipe', 'pipe'] })
-    : spawn(command, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
-  const prefix = \`\\x1b[\${colour}m\${name}\\x1b[0m │ \`;
-  for (const stream of [child.stdout, child.stderr]) {
-    let rest = '';
-    stream.on('data', (chunk) => {
-      const lines = (rest + chunk).split('\\n');
-      rest = lines.pop();
-      for (const line of lines) console.log(prefix + line);
-    });
-  }
-  child.on('exit', (code) => {
-    console.log(\`\${prefix}stopped\${code ? \` (exit \${code})\` : ''}\`);
-    stop();
-  });
-  return child;
-});
-
-let stopping = false;
-function stop() {
-  if (stopping) return;
-  stopping = true;
-  for (const child of running) {
-    // On Windows the child is a shell; killing it alone would leave php and node running.
-    if (shell && child.pid) spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
-    else child.kill();
-  }
-}
-process.on('SIGINT', stop);
-process.on('SIGTERM', stop);
-`);
-
   write(path.join(root, 'README.md'), `# ${title}
 
 A [Nevela](${DOCS}) app: a Laravel API in \`apps/api\` and a Next.js dashboard in \`apps/web\`.
@@ -287,10 +243,16 @@ A [Nevela](${DOCS}) app: a Laravel API in \`apps/api\` and a Next.js dashboard i
 ## Run it
 
 \`\`\`sh
-${pm} run dev
+php nevela dev
 \`\`\`
 
-That starts Laravel on http://127.0.0.1:8000 and the dashboard on http://localhost:3000. Sign in at http://localhost:3000/sign-in.
+That starts the Laravel API and the dashboard together and prints where each is: normally http://127.0.0.1:8000 and http://localhost:3000. If another program already has a port, it uses the next free one. Sign in at http://localhost:3000/sign-in.
+
+To check the app at any time (versions, migrations, users, and whether the dashboard is reaching this API):
+
+\`\`\`sh
+php nevela status
+\`\`\`
 ${admin ? `
 The app starts with one account, in your local database only:
 
@@ -303,6 +265,7 @@ Everything else runs from this folder too, with \`php nevela\`:
 
 \`\`\`sh
 php nevela user        # add someone who can sign in
+php nevela status      # versions, migrations, users, and what the dashboard is talking to
 php nevela update      # update Nevela and the dashboard
 php nevela             # everything it can do
 \`\`\`
@@ -426,7 +389,7 @@ async function main() {
   console.log(`    cd ${name}`);
   if (!options.install) console.log(`    cd apps/web && ${pm} install && cd ../..`);
   if (!admin) console.log(`    php nevela user   ${dim('# someone to sign in as')}`);
-  console.log(`    ${pm} run dev\n`);
+  console.log('    php nevela dev\n');
   console.log(`  Then open ${indigo('http://localhost:3000/sign-in')}${admin ? ' and sign in with:' : ''}`);
   if (admin) {
     console.log(`\n    Email      ${bold(ADMIN.email)}`);
@@ -434,7 +397,7 @@ async function main() {
     console.log(`  ${dim('That account is in this app\'s local database only. Add your own: php nevela user')}`);
   }
   console.log(`\n  Add your first resource: ${dim('php nevela resource Product --fields="name:string, price:money"')}`);
-  console.log(`  Everything runs from this folder: ${dim('php nevela')}`);
+  console.log(`  Check the app any time: ${dim('php nevela status')}   Everything else: ${dim('php nevela')}`);
   console.log(`  Docs: ${DOCS}/start/quickstart/\n`);
   if (outdated) console.log(outdated);
 }

package/package.json

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

package/template/laravel/src/Console/DevCommand.php

@@ -0,0 +1,104 @@
+<?php
+
+namespace Nevela\Laravel\Console;
+
+use Illuminate\Console\Command;
+use Symfony\Component\Process\PhpExecutableFinder;
+use Symfony\Component\Process\Process;
+
+final class DevCommand extends Command
+{
+    protected $signature = 'nevela:dev
+        {--port=8000 : The first port to try for the API}
+        {--api-only : Start the API without the dashboard}';
+
+    protected $description = 'Run the API and the dashboard together';
+
+    public function handle(): int
+    {
+        $wanted = max(1, (int) $this->option('port'));
+        $port = self::freePort($wanted);
+        if ($port === null) {
+            $this->components->error("Ports {$wanted} to ".($wanted + 19).' are all in use. Free one, or pass --port.');
+
+            return self::FAILURE;
+        }
+        if ($port !== $wanted) {
+            // Without this check the dashboard would talk to whatever already owns the port.
+            // On Windows two servers can listen on the same one, and the older one answers.
+            $this->components->warn("Port {$wanted} is already in use by another program, so the API is on {$port}.");
+        }
+        $url = "http://127.0.0.1:{$port}";
+
+        $php = (new PhpExecutableFinder)->find(false) ?: 'php';
+        $api = new Process([$php, 'artisan', 'serve', '--host=127.0.0.1', "--port={$port}"], base_path(), null, null, null);
+
+        $web = null;
+        $webPath = config('nevela.web_path');
+        if (! $this->option('api-only') && $webPath && is_dir($webPath)) {
+            // The dashboard is told where the API really is, whatever its .env.local says.
+            $web = Process::fromShellCommandline(self::packageManager($webPath).' run dev', $webPath, ['NEVELA_API_URL' => "{$url}/api"], null, null);
+        }
+
+        $this->components->info('Starting '.($web ? 'the API and the dashboard' : 'the API').'. Press Ctrl+C to stop.');
+        $this->components->twoColumnDetail('API', $url);
+        if ($web) {
+            $this->components->twoColumnDetail('Dashboard', 'http://localhost:3000/sign-in (see below if that port is taken)');
+        }
+        $this->newLine();
+
+        $api->start($this->printer('api', 35));
+        $web?->start($this->printer('web', 36));
+
+        try {
+            while ($api->isRunning() && ($web === null || $web->isRunning())) {
+                usleep(200_000);
+            }
+        } finally {
+            // Whichever stopped, or Ctrl+C: don't leave the other one running behind.
+            $web?->stop(3);
+            $api->stop(3);
+        }
+
+        return self::SUCCESS;
+    }
+
+    /** The first port from `$from` that nothing is listening on, or null if twenty in a row are taken. */
+    public static function freePort(int $from): ?int
+    {
+        for ($port = $from; $port < $from + 20; $port++) {
+            $socket = @fsockopen('127.0.0.1', $port, $code, $message, 0.3);
+            if ($socket === false) {
+                return $port;
+            }
+            fclose($socket);
+        }
+
+        return null;
+    }
+
+    /** The package manager a folder was installed with, from its lock file. */
+    public static function packageManager(string $dir): string
+    {
+        return match (true) {
+            is_file("{$dir}/pnpm-lock.yaml"), is_file("{$dir}/pnpm-workspace.yaml") => 'pnpm',
+            is_file("{$dir}/yarn.lock") => 'yarn',
+            is_file("{$dir}/bun.lockb"), is_file("{$dir}/bun.lock") => 'bun',
+            default => 'npm',
+        };
+    }
+
+    /** Prints a process's output a line at a time, each line labelled with which app it came from. */
+    private function printer(string $name, int $colour): \Closure
+    {
+        $rest = '';
+
+        return function (string $type, string $chunk) use ($name, $colour, &$rest) {
+            $lines = explode("\n", $rest.str_replace("\r\n", "\n", $chunk));
+            $rest = array_pop($lines);
+            foreach ($lines as $line) {
+                $this->output->writeln("\e[{$colour}m{$name}\e[0m │ ".$line, \Symfony\Component\Console\Output\OutputInterface::OUTPUT_RAW);
+            }
+        };
+    }
+}

package/template/laravel/src/Console/MakeResourceCommand.php

@@ -16,7 +16,8 @@ final class MakeResourceCommand extends Command
         {--icon= : Lucide icon name for the dashboard, e.g. package}
         {--group= : Sidebar group in the dashboard}
         {--force : Overwrite an existing descriptor}
-        {--migrate : Run the new migration straight away}';
+        {--migrate : Run the new migration straight away}
+        {--seed= : Fill the new resource with records too (25, or the number you give). Runs the migration first}';
 
     protected $description = 'Describe a resource once, then generate its Laravel API and Flare dashboard descriptor';
 
@@ -51,12 +52,19 @@ final class MakeResourceCommand extends Command
         Nevela::forget();
         $status = GenerateCommand::generate($this, [$descriptor], Nevela::all(), false);
 
-        if ($status === self::SUCCESS && $this->option('migrate')) {
+        // "--seed" on its own and "--seed=100" both count; without a number it is 25.
+        $seed = $this->input->hasParameterOption('--seed') || $this->option('seed') !== null;
+        $migrate = $this->option('migrate') || $seed;
+
+        if ($status === self::SUCCESS && $migrate) {
             $status = $this->call('migrate');
         }
+        if ($status === self::SUCCESS && $seed) {
+            $status = $this->call('nevela:seed', ['name' => $descriptor->name, '--count' => $this->option('seed') ?: 25]);
+        }
 
         $this->newLine();
-        $this->line($this->option('migrate')
+        $this->line($migrate
             ? '  Next: tighten <fg=cyan>app/Policies/'.$descriptor->name.'Policy.php</>.'
             : '  Next: <fg=cyan>php artisan migrate</>, then tighten <fg=cyan>app/Policies/'.$descriptor->name.'Policy.php</>.');
         $this->line("  API:  GET|POST /{$this->prefix()}{$descriptor->slug} · GET|PUT|PATCH|DELETE /{$this->prefix()}{$descriptor->slug}/{id} · GET /{$this->prefix()}{$descriptor->slug}/_stats");

package/template/laravel/src/Console/StatusCommand.php

@@ -0,0 +1,172 @@
+<?php
+
+namespace Nevela\Laravel\Console;
+
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Http;
+use Nevela\Laravel\Nevela;
+use Nevela\Laravel\Support\Releases;
+use Throwable;
+
+final class StatusCommand extends Command
+{
+    protected $signature = 'nevela:status';
+
+    protected $description = 'Check the app: versions, the database, migrations, users, resources and the dashboard';
+
+    public function handle(): int
+    {
+        $problems = 0;
+        $row = fn (string $label, string $value) => $this->components->twoColumnDetail($label, $value);
+        $bad = function (string $text) use (&$problems): string {
+            $problems++;
+
+            return "<fg=red>{$text}</>";
+        };
+
+        $this->newLine();
+        $latest = Releases::latest();
+        $row('Nevela', Nevela::VERSION.match (true) {
+            $latest === null => ' <fg=gray>(couldn\'t check for a newer one)</>',
+            version_compare($latest, Nevela::VERSION, '>') => " <fg=yellow>({$latest} is out: php nevela update)</>",
+            default => ' <fg=green>(latest)</>',
+        });
+        $row('Laravel / PHP', app()->version().' / '.PHP_VERSION);
+
+        // --- database ---
+        try {
+            $connection = DB::connection();
+            $connection->getPdo();
+            $name = $connection->getDatabaseName();
+            $row('Database', $connection->getDriverName().($name ? ' · '.str_replace(base_path().DIRECTORY_SEPARATOR, '', (string) $name) : ''));
+
+            $migrator = app('migrator');
+            if (! $migrator->repositoryExists()) {
+                $row('Migrations', $bad('none have run: php nevela migrate'));
+            } else {
+                $ran = $migrator->getRepository()->getRan();
+                $files = array_keys($migrator->getMigrationFiles([...$migrator->paths(), database_path('migrations')]));
+                $pending = array_values(array_diff($files, $ran));
+                $row('Migrations', count($ran).' ran, '.($pending === []
+                    ? '<fg=green>none pending</>'
+                    : $bad(count($pending).' pending: php nevela migrate')));
+                foreach ($pending as $migration) {
+                    $this->line("    <fg=gray>pending</> {$migration}");
+                }
+            }
+
+            $model = config('auth.providers.users.model');
+            if (is_string($model) && class_exists($model)) {
+                try {
+                    $users = $model::query()->count();
+                    $row('Users who can sign in', $users > 0 ? (string) $users : $bad('none: php nevela user'));
+                } catch (Throwable) {
+                    $row('Users who can sign in', $bad('the users table is missing: php nevela migrate'));
+                }
+            }
+        } catch (Throwable $e) {
+            $row('Database', $bad('can\'t connect: '.str($e->getMessage())->limit(90)));
+        }
+
+        // --- resources ---
+        try {
+            $resources = Nevela::all();
+        } catch (Throwable $e) {
+            $resources = [];
+            $row('Resources', $bad('a descriptor can\'t be read: '.str($e->getMessage())->limit(90)));
+        }
+        if ($resources === []) {
+            $row('Resources', '<fg=gray>none yet: php nevela resource Product --fields="name:string"</>');
+        }
+        foreach ($resources as $resource) {
+            try {
+                $row("Resource: {$resource->name}", number_format(DB::table($resource->table)->count()).' records');
+            } catch (Throwable) {
+                $row("Resource: {$resource->name}", $bad("the {$resource->table} table is missing: php nevela migrate"));
+            }
+        }
+
+        // --- dashboard ---
+        $web = config('nevela.web_path');
+        if (! $web || ! is_dir($web)) {
+            $row('Dashboard', '<fg=gray>not found at nevela.web_path</>');
+        } else {
+            $marker = json_decode((string) @file_get_contents(rtrim($web, '/\\').'/.nevela.json'), true);
+            $row('Dashboard', is_array($marker) && isset($marker['template']) ? "template {$marker['template']}" : '<fg=gray>template version not recorded</>');
+
+            // `php nevela dev` may have put the API on another port and told the dashboard so,
+            // which is fine. Look for this app wherever it is running before judging.
+            $url = self::apiUrl($web);
+            $who = self::whoAnswers($url);
+            $running = $who === 'this' ? $url : self::findRunning();
+
+            if ($who === 'this') {
+                $row('API', "{$url} <fg=green>(running, and it is this app)</>");
+            } elseif ($running !== null) {
+                $row('API', "{$running} <fg=green>(running, and it is this app)</>");
+                $row('', '<fg=gray>'.parse_url($url, PHP_URL_PORT).' belongs to another program; php nevela dev chose a free port</>');
+            } elseif ($who === 'nobody') {
+                $row('API', '<fg=gray>not running: php nevela dev</>');
+            } else {
+                $row('API', $bad("{$url} is answered by ".($who === 'nevela' ? 'another Nevela app' : 'another program').', not this app'));
+                $row('', '<fg=gray>start with php nevela dev, which picks a free port and tells the dashboard</>');
+            }
+        }
+        $this->newLine();
+
+        if ($problems > 0) {
+            $this->components->warn($problems === 1 ? 'One thing needs attention, marked in red above.' : "{$problems} things need attention, marked in red above.");
+
+            return self::FAILURE;
+        }
+        $this->components->info('Everything looks right.');
+
+        return self::SUCCESS;
+    }
+
+    /** Where the dashboard is told the API is: NEVELA_API_URL in its .env.local, else the default. */
+    public static function apiUrl(string $web): string
+    {
+        $env = (string) @file_get_contents(rtrim($web, '/\\').'/.env.local');
+        if (preg_match('/^\s*NEVELA_API_URL\s*=\s*["\']?([^"\'\r\n#]+)/m', $env, $m)) {
+            return rtrim(trim($m[1]), '/');
+        }
+
+        return 'http://127.0.0.1:8000/api';
+    }
+
+    /** Who answers at an API address: 'this' app, another 'nevela' app, some 'other' program, or 'nobody'. */
+    public static function whoAnswers(string $url): string
+    {
+        try {
+            $response = Http::timeout(3)->acceptJson()->get($url.'/_nevela/ping');
+        } catch (Throwable) {
+            return 'nobody';
+        }
+        if ($response->json('app') === Nevela::fingerprint()) {
+            return 'this';
+        }
+
+        return $response->json('nevela') !== null ? 'nevela' : 'other';
+    }
+
+    /** This app's API on one of the ports `php nevela dev` would use, or null if it isn't running. */
+    private static function findRunning(): ?string
+    {
+        $prefix = trim((string) config('nevela.prefix', 'api'), '/');
+        for ($port = 8000; $port < 8020; $port++) {
+            $socket = @fsockopen('127.0.0.1', $port, $code, $message, 0.15);
+            if ($socket === false) {
+                continue;
+            }
+            fclose($socket);
+            $url = "http://127.0.0.1:{$port}".($prefix === '' ? '' : "/{$prefix}");
+            if (self::whoAnswers($url) === 'this') {
+                return $url;
+            }
+        }
+
+        return null;
+    }
+}

package/template/laravel/src/Console/UpdateCommand.php

@@ -6,6 +6,7 @@ use Illuminate\Console\Command;
 use Illuminate\Support\Facades\Http;
 use Nevela\Laravel\Nevela;
 use Nevela\Laravel\Support\DashboardUpdate;
+use Nevela\Laravel\Support\Releases;
 use PharData;
 use RecursiveDirectoryIterator;
 use RecursiveIteratorIterator;
@@ -37,11 +38,32 @@ final class UpdateCommand extends Command
 
         if (! $check) {
             $this->components->task('Regenerating from the descriptors', fn () => $this->callSilently('nevela:generate') === self::SUCCESS);
+            $this->modernizeDevScript();
         }
 
         return $this->updateDashboard($check);
     }
 
+    /**
+     * Apps created before 0.1.3 run both servers with scripts/dev.mjs, which always uses
+     * port 8000 and so can end up talking to another program that already has it. Point
+     * their `dev` script at `php nevela dev`, which picks a free port, unless they changed it.
+     */
+    private function modernizeDevScript(): void
+    {
+        $root = GenerateCommand::projectRoot();
+        $file = $root ? $root.DIRECTORY_SEPARATOR.'package.json' : null;
+        if (! $file || ! is_file($file)) {
+            return;
+        }
+        $source = (string) file_get_contents($file);
+        $updated = preg_replace('/("dev"\s*:\s*)"node scripts\/dev\.mjs"/', '$1"php nevela dev"', $source, 1, $count);
+        if ($count === 1) {
+            file_put_contents($file, $updated);
+            $this->components->twoColumnDetail('package.json: dev', '<fg=blue>node scripts/dev.mjs → php nevela dev</>');
+        }
+    }
+
     /**
      * Update the Composer package. Returns an exit code when the rest of the work was
      * handed to a fresh process, or null to carry on in this one.
@@ -49,7 +71,7 @@ final class UpdateCommand extends Command
     private function updatePackage(bool $check): ?int
     {
         $installed = Nevela::VERSION;
-        $latest = $this->latestOnPackagist();
+        $latest = Releases::latest();
 
         if ($folder = $this->installedByPath()) {
             $this->components->warn("nevela/laravel is installed from a folder ({$folder}), so Composer can't update it. The dashboard is checked against the version you have, {$installed}.");
@@ -115,7 +137,7 @@ final class UpdateCommand extends Command
         $marker = "{$web}/.nevela.json";
         $from = is_file($marker) ? (json_decode((string) file_get_contents($marker), true)['template'] ?? self::FIRST_TRACKED) : self::FIRST_TRACKED;
         // In --check the package hasn't been updated, so look at the newest dashboard there is.
-        $to = $check ? ($this->latestOnPackagist() ?? Nevela::VERSION) : Nevela::VERSION;
+        $to = $check ? (Releases::latest() ?? Nevela::VERSION) : Nevela::VERSION;
 
         if (version_compare($from, $to, '>=')) {
             $this->components->info("The dashboard is on the latest template ({$from}).");
@@ -246,29 +268,6 @@ final class UpdateCommand extends Command
         }
     }
 
-    /** The newest stable release on Packagist, or null when it can't be reached. */
-    private function latestOnPackagist(): ?string
-    {
-        static $latest = false;
-        if ($latest !== false) {
-            return $latest;
-        }
-        try {
-            $releases = Http::timeout(10)->get('https://repo.packagist.org/p2/nevela/laravel.json')->json('packages.nevela/laravel') ?? [];
-        } catch (Throwable) {
-            return $latest = null;
-        }
-        $versions = [];
-        foreach ($releases as $release) {
-            if (preg_match('/^v?(\d+\.\d+\.\d+)$/', (string) ($release['version'] ?? ''), $m)) {
-                $versions[] = $m[1];
-            }
-        }
-        usort($versions, 'version_compare');
-
-        return $latest = ($versions === [] ? null : end($versions));
-    }
-
     /** The folder Composer installs the package from, when it isn't coming from Packagist. */
     private function installedByPath(): ?string
     {

package/template/laravel/src/Console/VersionCommand.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Nevela\Laravel\Console;
+
+use Illuminate\Console\Command;
+use Nevela\Laravel\Nevela;
+
+final class VersionCommand extends Command
+{
+    protected $signature = 'nevela:version';
+
+    protected $description = 'Show which version of Nevela this app is on';
+
+    public function handle(): int
+    {
+        $this->line('Nevela '.Nevela::VERSION);
+
+        return self::SUCCESS;
+    }
+}

package/template/laravel/src/Generator/ResourceGenerator.php

@@ -172,13 +172,10 @@ final class ResourceGenerator
         \$name = array_shift(\$args) ?? 'help';
 
         // What you type => the artisan command it runs.
-        \$nevela = ['resource', 'generate', 'seed', 'user', 'update'];
+        \$nevela = ['resource', 'generate', 'seed', 'user', 'update', 'dev', 'status', 'version'];
         \$artisan = ['migrate', 'tinker', 'test', 'serve'];
-
-        if (\$name === 'dev') {
-            // The API and the dashboard together.
-            passthru('node '.escapeshellarg(__DIR__.'/scripts/dev.mjs'), \$status);
-            exit(\$status);
+        if (in_array(\$name, ['--version', '-v', '-V'], true)) {
+            \$name = 'version';
         }
 
         if (in_array(\$name, \$nevela, true)) {
@@ -197,12 +194,15 @@ final class ResourceGenerator
 
               Nevela, from the top of your project.
 
-              php nevela resource Product --fields="name:string, price:money"   add a resource and migrate
+              php nevela dev                   run the API and the dashboard
+              php nevela status                check versions, migrations, users and the dashboard
+              php nevela resource Product --fields="name:string, price:money" --seed
+                                               add a resource, create its table, fill it
               php nevela generate              regenerate after editing a descriptor
               php nevela seed Product          fill a resource with records
               php nevela user                  create someone who can sign in
               php nevela update                update Nevela and the dashboard
-              php nevela dev                   run the API and the dashboard
+              php nevela version               which Nevela this is
 
               php nevela migrate               php artisan migrate
               php nevela artisan <command>     any other artisan command

package/template/laravel/src/Nevela.php

@@ -1,151 +1,161 @@
-<?php
-
-namespace Nevela\Laravel;
-
-use Illuminate\Database\Eloquent\Builder;
-use Illuminate\Http\JsonResponse;
-use Illuminate\Http\Request;
-use InvalidArgumentException;
-use Nevela\Laravel\Support\Descriptor;
-use Nevela\Laravel\Support\ListQuery;
-use Nevela\Laravel\Support\Naming;
-
-/**
- * Runtime helpers the generated controllers call. Kept small and readable: each method is
- * one step of Flare's REST contract.
- */
-final class Nevela
-{
-    /** Written by `pnpm release`; the same number as the repository's git tag. */
-    public const VERSION = '0.1.2';
-
-    /** @var array<string, Descriptor> */
-    private static array $descriptors = [];
-
-    /** A resource's descriptor, from config('nevela.descriptors_path')/<kebab-name>.json. */
-    public static function resource(string $name): Descriptor
-    {
-        if (isset(self::$descriptors[$name])) {
-            return self::$descriptors[$name];
-        }
-        $path = rtrim(config('nevela.descriptors_path'), '/\\').DIRECTORY_SEPARATOR.Naming::kebab($name).'.json';
-        if (! is_file($path)) {
-            throw new InvalidArgumentException("No Nevela descriptor for {$name} at {$path}.");
-        }
-
-        return self::$descriptors[$name] = Descriptor::fromJson((string) file_get_contents($path));
-    }
-
-    /** @return list<Descriptor> */
-    public static function all(): array
-    {
-        $dir = config('nevela.descriptors_path');
-        $all = [];
-        foreach (glob(rtrim($dir, '/\\').DIRECTORY_SEPARATOR.'*.json') ?: [] as $file) {
-            $d = Descriptor::fromJson((string) file_get_contents($file));
-            $all[] = self::$descriptors[$d->name] = $d;
-        }
-
-        return $all;
-    }
-
-    public static function forget(): void
-    {
-        self::$descriptors = [];
-    }
-
-    /**
-     * GET /{slug}: page, perPage, sort, q, filter[field] → { data, meta }.
-     *
-     * @param  class-string<\Illuminate\Http\Resources\Json\JsonResource>  $resourceClass
-     */
-    public static function list(Builder $query, string $name, Request $request, string $resourceClass): JsonResponse
-    {
-        $resource = self::resource($name);
-        $list = ListQuery::parse($resource, $request->query(), (int) config('nevela.per_page', 25), (int) config('nevela.max_per_page', 100));
-        if (! $list->ok()) {
-            return response()->json(['error' => 'Invalid query.', 'issues' => $list->issues], 400);
-        }
-
-        if ($list->q !== null) {
-            $columns = array_map(fn ($f) => $f->column(), array_values(array_filter($resource->fields, fn ($f) => $f->searchable())));
-            if ($columns !== []) {
-                $pattern = '%'.addcslashes($list->q, '%_\\').'%';
-                $query->where(function (Builder $where) use ($columns, $pattern) {
-                    foreach ($columns as $column) {
-                        $where->orWhereLike($column, $pattern);
-                    }
-                });
-            }
-        }
-
-        foreach ($list->filters as $filter) {
-            $filter['value'] === null
-                ? $query->whereNull($filter['column'])
-                : $query->where($filter['column'], $filter['value']);
-        }
-
-        $query->reorder()
-            ->orderBy($list->sort['column'], $list->sort['direction'])
-            ->orderBy($query->getModel()->getKeyName(), $list->sort['direction']);
-
-        $page = $query->paginate($list->perPage, ['*'], 'page', $list->page);
-
-        return response()->json([
-            'data' => $resourceClass::collection($page->getCollection())->resolve($request),
-            'meta' => [
-                'page' => $page->currentPage(),
-                'perPage' => $page->perPage(),
-                'total' => $page->total(),
-                'totalPages' => max(1, $page->lastPage()),
-            ],
-        ]);
-    }
-
-    /**
-     * GET /{slug}/_stats?field=status&days=7 → { total, current, previous, values }.
-     * What Flare's ResourceStats card shows above a table.
-     */
-    public static function stats(Builder $query, string $name, Request $request): JsonResponse
-    {
-        $resource = self::resource($name);
-        $days = filter_var($request->query('days', 7), FILTER_VALIDATE_INT, ['options' => ['min_range' => 1, 'max_range' => 365]]);
-        if ($days === false) {
-            return response()->json(['error' => 'Invalid query.', 'issues' => [['param' => 'days', 'message' => 'Must be between 1 and 365.']]], 400);
-        }
-        $key = $request->query('field');
-        $field = is_string($key) ? ($resource->fields[$key] ?? null) : null;
-        if ($key !== null && ($field === null || ! in_array($field->kind, ['enum', 'boolean'], true))) {
-            return response()->json(['error' => 'Invalid query.', 'issues' => [['param' => 'field', 'message' => 'Must be an enum or boolean field.']]], 400);
-        }
-
-        $now = now();
-        $since = $now->copy()->subDays($days);
-        $before = $now->copy()->subDays($days * 2);
-        $base = fn () => (clone $query)->reorder();
-
-        $values = [];
-        if ($field !== null) {
-            $column = $field->column();
-            foreach ($base()->toBase()->select($column.' as value')->selectRaw('count(*) as aggregate')->groupBy($column)->get() as $row) {
-                $value = $field->kind === 'boolean' ? ($row->value ? 'true' : 'false') : (string) $row->value;
-                $values[$value] = (int) $row->aggregate;
-            }
-        }
-
-        return response()->json([
-            'total' => $base()->count(),
-            'current' => $base()->where('created_at', '>=', $since)->count(),
-            'previous' => $base()->where('created_at', '>=', $before)->where('created_at', '<', $since)->count(),
-            'values' => (object) $values,
-        ]);
-    }
-
-    /** Whether a request is one Nevela answers (so errors use Flare's shape). */
-    public static function handles(Request $request): bool
-    {
-        $prefix = trim((string) config('nevela.prefix', 'api'), '/');
-
-        return $prefix === '' || $request->is($prefix, $prefix.'/*');
-    }
-}
+<?php
+
+namespace Nevela\Laravel;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use InvalidArgumentException;
+use Nevela\Laravel\Support\Descriptor;
+use Nevela\Laravel\Support\ListQuery;
+use Nevela\Laravel\Support\Naming;
+
+/**
+ * Runtime helpers the generated controllers call. Kept small and readable: each method is
+ * one step of Flare's REST contract.
+ */
+final class Nevela
+{
+    /** Written by `pnpm release`; the same number as the repository's git tag. */
+    public const VERSION = '0.1.3';
+
+    /** @var array<string, Descriptor> */
+    private static array $descriptors = [];
+
+    /**
+     * A short id for this installation, from where it is on disk. It gives nothing away,
+     * and it differs between two apps on one machine, which is what it is for: telling
+     * which app is answering on a port.
+     */
+    public static function fingerprint(): string
+    {
+        return substr(sha1(base_path()), 0, 12);
+    }
+
+    /** A resource's descriptor, from config('nevela.descriptors_path')/<kebab-name>.json. */
+    public static function resource(string $name): Descriptor
+    {
+        if (isset(self::$descriptors[$name])) {
+            return self::$descriptors[$name];
+        }
+        $path = rtrim(config('nevela.descriptors_path'), '/\\').DIRECTORY_SEPARATOR.Naming::kebab($name).'.json';
+        if (! is_file($path)) {
+            throw new InvalidArgumentException("No Nevela descriptor for {$name} at {$path}.");
+        }
+
+        return self::$descriptors[$name] = Descriptor::fromJson((string) file_get_contents($path));
+    }
+
+    /** @return list<Descriptor> */
+    public static function all(): array
+    {
+        $dir = config('nevela.descriptors_path');
+        $all = [];
+        foreach (glob(rtrim($dir, '/\\').DIRECTORY_SEPARATOR.'*.json') ?: [] as $file) {
+            $d = Descriptor::fromJson((string) file_get_contents($file));
+            $all[] = self::$descriptors[$d->name] = $d;
+        }
+
+        return $all;
+    }
+
+    public static function forget(): void
+    {
+        self::$descriptors = [];
+    }
+
+    /**
+     * GET /{slug}: page, perPage, sort, q, filter[field] → { data, meta }.
+     *
+     * @param  class-string<\Illuminate\Http\Resources\Json\JsonResource>  $resourceClass
+     */
+    public static function list(Builder $query, string $name, Request $request, string $resourceClass): JsonResponse
+    {
+        $resource = self::resource($name);
+        $list = ListQuery::parse($resource, $request->query(), (int) config('nevela.per_page', 25), (int) config('nevela.max_per_page', 100));
+        if (! $list->ok()) {
+            return response()->json(['error' => 'Invalid query.', 'issues' => $list->issues], 400);
+        }
+
+        if ($list->q !== null) {
+            $columns = array_map(fn ($f) => $f->column(), array_values(array_filter($resource->fields, fn ($f) => $f->searchable())));
+            if ($columns !== []) {
+                $pattern = '%'.addcslashes($list->q, '%_\\').'%';
+                $query->where(function (Builder $where) use ($columns, $pattern) {
+                    foreach ($columns as $column) {
+                        $where->orWhereLike($column, $pattern);
+                    }
+                });
+            }
+        }
+
+        foreach ($list->filters as $filter) {
+            $filter['value'] === null
+                ? $query->whereNull($filter['column'])
+                : $query->where($filter['column'], $filter['value']);
+        }
+
+        $query->reorder()
+            ->orderBy($list->sort['column'], $list->sort['direction'])
+            ->orderBy($query->getModel()->getKeyName(), $list->sort['direction']);
+
+        $page = $query->paginate($list->perPage, ['*'], 'page', $list->page);
+
+        return response()->json([
+            'data' => $resourceClass::collection($page->getCollection())->resolve($request),
+            'meta' => [
+                'page' => $page->currentPage(),
+                'perPage' => $page->perPage(),
+                'total' => $page->total(),
+                'totalPages' => max(1, $page->lastPage()),
+            ],
+        ]);
+    }
+
+    /**
+     * GET /{slug}/_stats?field=status&days=7 → { total, current, previous, values }.
+     * What Flare's ResourceStats card shows above a table.
+     */
+    public static function stats(Builder $query, string $name, Request $request): JsonResponse
+    {
+        $resource = self::resource($name);
+        $days = filter_var($request->query('days', 7), FILTER_VALIDATE_INT, ['options' => ['min_range' => 1, 'max_range' => 365]]);
+        if ($days === false) {
+            return response()->json(['error' => 'Invalid query.', 'issues' => [['param' => 'days', 'message' => 'Must be between 1 and 365.']]], 400);
+        }
+        $key = $request->query('field');
+        $field = is_string($key) ? ($resource->fields[$key] ?? null) : null;
+        if ($key !== null && ($field === null || ! in_array($field->kind, ['enum', 'boolean'], true))) {
+            return response()->json(['error' => 'Invalid query.', 'issues' => [['param' => 'field', 'message' => 'Must be an enum or boolean field.']]], 400);
+        }
+
+        $now = now();
+        $since = $now->copy()->subDays($days);
+        $before = $now->copy()->subDays($days * 2);
+        $base = fn () => (clone $query)->reorder();
+
+        $values = [];
+        if ($field !== null) {
+            $column = $field->column();
+            foreach ($base()->toBase()->select($column.' as value')->selectRaw('count(*) as aggregate')->groupBy($column)->get() as $row) {
+                $value = $field->kind === 'boolean' ? ($row->value ? 'true' : 'false') : (string) $row->value;
+                $values[$value] = (int) $row->aggregate;
+            }
+        }
+
+        return response()->json([
+            'total' => $base()->count(),
+            'current' => $base()->where('created_at', '>=', $since)->count(),
+            'previous' => $base()->where('created_at', '>=', $before)->where('created_at', '<', $since)->count(),
+            'values' => (object) $values,
+        ]);
+    }
+
+    /** Whether a request is one Nevela answers (so errors use Flare's shape). */
+    public static function handles(Request $request): bool
+    {
+        $prefix = trim((string) config('nevela.prefix', 'api'), '/');
+
+        return $prefix === '' || $request->is($prefix, $prefix.'/*');
+    }
+}

package/template/laravel/src/NevelaServiceProvider.php

@@ -5,11 +5,14 @@ namespace Nevela\Laravel;
 use Illuminate\Contracts\Debug\ExceptionHandler;
 use Illuminate\Support\Facades\Route;
 use Illuminate\Support\ServiceProvider;
+use Nevela\Laravel\Console\DevCommand;
 use Nevela\Laravel\Console\GenerateCommand;
 use Nevela\Laravel\Console\MakeResourceCommand;
 use Nevela\Laravel\Console\SeedCommand;
+use Nevela\Laravel\Console\StatusCommand;
 use Nevela\Laravel\Console\UpdateCommand;
 use Nevela\Laravel\Console\UserCommand;
+use Nevela\Laravel\Console\VersionCommand;
 use Nevela\Laravel\Http\FlareErrors;
 use Nevela\Laravel\Http\TokenController;
 
@@ -24,7 +27,10 @@ final class NevelaServiceProvider extends ServiceProvider
     {
         if ($this->app->runningInConsole()) {
             $this->publishes([__DIR__.'/../config/nevela.php' => config_path('nevela.php')], 'nevela-config');
-            $this->commands([MakeResourceCommand::class, GenerateCommand::class, SeedCommand::class, UserCommand::class, UpdateCommand::class]);
+            $this->commands([
+                MakeResourceCommand::class, GenerateCommand::class, SeedCommand::class, UserCommand::class,
+                UpdateCommand::class, DevCommand::class, StatusCommand::class, VersionCommand::class,
+            ]);
         }
 
         $this->callAfterResolving(ExceptionHandler::class, function ($handler) {
@@ -52,6 +58,13 @@ final class NevelaServiceProvider extends ServiceProvider
             });
         }
 
+        // Open to anyone, and says only that this is a Nevela app and which one. It is how the
+        // dashboard and `nevela:status` tell this app from another program on the same port.
+        Route::prefix($prefix)->middleware(['api', 'throttle:60,1'])->get('_nevela/ping', fn () => response()->json([
+            'nevela' => Nevela::VERSION,
+            'app' => Nevela::fingerprint(),
+        ]))->name('nevela.ping');
+
         Route::prefix($prefix)->middleware(config('nevela.middleware', ['api', 'auth:sanctum']))->name('nevela.')->group(function () {
             // The descriptors, so the web app (and tooling) can check it matches the API.
             Route::get('_nevela/resources', fn () => response()->json([

package/template/laravel/src/Support/Releases.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace Nevela\Laravel\Support;
+
+use Illuminate\Support\Facades\Http;
+use Throwable;
+
+/** What Packagist knows about nevela/laravel. */
+final class Releases
+{
+    private static string|null|false $latest = false;
+
+    /** The newest stable release, or null when Packagist can't be reached. Asked once per run. */
+    public static function latest(): ?string
+    {
+        if (self::$latest !== false) {
+            return self::$latest;
+        }
+        try {
+            $releases = Http::timeout(8)->get('https://repo.packagist.org/p2/nevela/laravel.json')->json('packages.nevela/laravel') ?? [];
+        } catch (Throwable) {
+            return self::$latest = null;
+        }
+
+        return self::$latest = self::newest(array_map(fn ($release) => (string) ($release['version'] ?? ''), $releases));
+    }
+
+    /**
+     * The highest x.y.z in a list of version names. Branches and pre-releases don't count.
+     *
+     * @param  list<string>  $names
+     */
+    public static function newest(array $names): ?string
+    {
+        $versions = [];
+        foreach ($names as $name) {
+            if (preg_match('/^v?(\d+\.\d+\.\d+)$/', $name, $m)) {
+                $versions[] = $m[1];
+            }
+        }
+        usort($versions, 'version_compare');
+
+        return $versions === [] ? null : end($versions);
+    }
+}

package/template/web/app/auth-actions.ts

@@ -1,7 +1,7 @@
 "use server";
 
 import { cookies } from "next/headers";
-import { laravel, TOKEN_COOKIE } from "@/lib/laravel";
+import { API_URL, laravel, TOKEN_COOKIE } from "@/lib/laravel";
 
 export type SignInResult = { ok: true } | { ok: false; error: string };
 
@@ -17,12 +17,20 @@ export async function signInAction(email: string, password: string): Promise<Sig
   try {
     response = await laravel("auth/token", { method: "POST", body: { email, password }, token: null });
   } catch {
-    return { ok: false, error: "Can't reach the server. Check that the Laravel app is running." };
+    return { ok: false, error: `Can't reach the server at ${API_URL}. Start it with: php nevela dev` };
   }
   if (!response.ok) {
-    const body = (response.body ?? {}) as { error?: string; issues?: { message: string }[] };
+    const body = (response.body ?? {}) as { error?: string; message?: string; issues?: { message: string }[] };
     if (response.status === 429) return { ok: false, error: "Too many attempts. Wait a minute and try again." };
-    return { ok: false, error: body.issues?.[0]?.message ?? body.error ?? "Sign-in failed. Try again." };
+    if (response.status === 404 || response.status === 405) {
+      // Something answered, but it has no sign-in route: it isn't this app's API. Usually
+      // another program already had the port when the API was started.
+      return {
+        ok: false,
+        error: `${API_URL} is answered by a different program, not this app's API. Stop what is using that port, or start both with "php nevela dev", which picks a free one.`,
+      };
+    }
+    return { ok: false, error: body.issues?.[0]?.message ?? body.error ?? body.message ?? "Sign-in failed. Try again." };
   }
 
   const { token } = response.body as { token: string };

package/template/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nevela-web",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "private": true,
   "type": "module",
   "scripts": {