create-nevela 0.1.2 → 0.1.4

package/project.mjs

@@ -0,0 +1,126 @@
+// `nevela <command>` inside an existing app.
+//
+// The same commands as the app's own `php nevela`, but started from Node. That matters in
+// shells where typing `php` doesn't work (Git Bash with Laravel Herd, where PHP is
+// php.bat), and for `update`, which has to work on an app of any age, including one from
+// before the app had a launcher at all.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnCommand } from './shell.mjs';
+
+/** What `nevela <name>` runs: these go to `php artisan nevela:<name>`. */
+const NEVELA = ['update', 'dev', 'status', 'version', 'resource', 'generate', 'seed', 'user'];
+/** These go to the artisan command of the same name. */
+const ARTISAN = ['migrate', 'tinker', 'test', 'serve'];
+
+export const COMMANDS = [...NEVELA, ...ARTISAN, 'artisan'];
+
+/** The app this folder belongs to: the nearest parent holding apps/api/artisan. */
+export function findProject(from) {
+  let dir = path.resolve(from);
+  for (;;) {
+    if (fs.existsSync(path.join(dir, 'apps', 'api', 'artisan'))) {
+      return { root: dir, api: path.join(dir, 'apps', 'api'), web: path.join(dir, 'apps', 'web') };
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/** The artisan arguments for `nevela <name> …args`. */
+export function artisanArguments(name, args) {
+  if (name === 'artisan') return args;
+  if (ARTISAN.includes(name)) return [name, ...args];
+  // A new resource is no use until its table exists, so make it in the same step.
+  const rest = args.filter((arg) => arg !== '--no-migrate');
+  if (name === 'resource' && !args.includes('--no-migrate')) rest.push('--migrate');
+  return [`nevela:${name}`, ...rest];
+}
+
+/**
+ * What stops Composer from updating nevela/laravel, repaired in composer.json.
+ * Returns a line describing each repair, for the user to see.
+ */
+export function repairManifest(manifest, latest) {
+  const repairs = [];
+  const current = manifest.require?.['nevela/laravel'];
+  const caret = latest ? `^${latest.split('.').slice(0, 2).join('.')}` : null;
+
+  // Installed from a folder in the app, from before the package was on Packagist.
+  const repositories = Array.isArray(manifest.repositories) ? manifest.repositories : Object.values(manifest.repositories ?? {});
+  const bundled = repositories.filter((repo) => repo?.type === 'path' && /nevela-laravel\/?$/.test(String(repo.url).replace(/\\/g, '/')));
+  if (bundled.length && caret) {
+    const kept = repositories.filter((repo) => !bundled.includes(repo));
+    if (kept.length) manifest.repositories = kept;
+    else delete manifest.repositories;
+    manifest.require['nevela/laravel'] = caret;
+    repairs.push(`nevela/laravel now comes from Packagist (${caret}) instead of the packages/nevela-laravel folder, which you can delete`);
+    return repairs;
+  }
+
+  // Windows installs from create-nevela 0.1.0 dropped the caret: "0.1" pins one exact version.
+  if (typeof current === 'string' && /^\d+\.\d+(\.\d+)?$/.test(current)) {
+    manifest.require['nevela/laravel'] = caret ?? `^${current.split('.').slice(0, 2).join('.')}`;
+    repairs.push(`"nevela/laravel": "${current}" pinned one exact version; it is now "${manifest.require['nevela/laravel']}"`);
+  }
+  return repairs;
+}
+
+/** Make sure `pnpm nevela …` and a port-safe `dev` exist in the app's root package.json. */
+export function repairScripts(root) {
+  const file = path.join(root, 'package.json');
+  if (!fs.existsSync(file)) return [];
+  const manifest = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const repairs = [];
+  manifest.scripts ??= {};
+  if (!manifest.scripts.nevela) {
+    manifest.scripts.nevela = 'php nevela';
+    repairs.push('added the "nevela" script: pnpm nevela <command>');
+  }
+  if (manifest.scripts.dev === 'node scripts/dev.mjs') {
+    manifest.scripts.dev = 'php nevela dev';
+    repairs.push('"dev" now runs php nevela dev, which picks a free port');
+  }
+  if (repairs.length) fs.writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`);
+  return repairs;
+}
+
+/** Run a command in the app's Laravel folder, attached to this terminal. Returns its exit code. */
+function inApp(project, command, args) {
+  const result = spawnCommand(command, args, { cwd: project.api, stdio: 'inherit' });
+  if (result.error) {
+    console.error(`\n  Couldn't run ${command}: ${result.error.message}\n`);
+    return 1;
+  }
+  return result.status ?? 1;
+}
+
+/** `nevela update`: bring an app of any age to the latest Nevela. */
+export async function update(project, args, { latest, say }) {
+  const check = args.includes('--check');
+  const manifestFile = path.join(project.api, 'composer.json');
+  const manifest = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
+  const before = JSON.stringify(manifest);
+  const repairs = repairManifest(manifest, latest);
+
+  if (!check) {
+    if (JSON.stringify(manifest) !== before) fs.writeFileSync(manifestFile, `${JSON.stringify(manifest, null, 4)}\n`);
+    repairs.push(...repairScripts(project.root));
+    for (const repair of repairs) say(repair);
+
+    // Composer first, from here: an app from before 0.1.2 has no update command of its own yet.
+    const status = inApp(project, 'composer', ['update', 'nevela/laravel', '--no-interaction', '--no-progress']);
+    if (status !== 0) return status;
+    return inApp(project, 'php', ['artisan', 'nevela:update', '--skip-package', ...args]);
+  }
+
+  for (const repair of repairs) say(`would fix: ${repair}`);
+  return inApp(project, 'php', ['artisan', 'nevela:update', ...args]);
+}
+
+/** Any other command: hand it to artisan in the app. */
+export function forward(project, name, args) {
+  return inApp(project, 'php', ['artisan', ...artisanArguments(name, args)]);
+}

package/selfupdate.mjs

@@ -0,0 +1,94 @@
+// Always run the newest installer, whatever version the package manager handed over.
+//
+// pnpm skips versions published in the last few hours, and both pnpm and npm cache what
+// `create` resolved to. Left alone, `pnpm create nevela` runs a stale installer for a while
+// after every release. So the first thing any installer does is ask npm what the newest
+// version is, and if that isn't this one, download it and hand over.
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { isNewer } from './packagist.mjs';
+
+const REGISTRY = 'https://registry.npmjs.org/create-nevela';
+
+/** The newest create-nevela on npm when it is newer than `current`, else null. Never throws. */
+export async function newerVersion(current) {
+  try {
+    const response = await fetch(`${REGISTRY}/latest`, { signal: AbortSignal.timeout(4000) });
+    const latest = (await response.json()).version;
+    return isNewer(latest, current) ? latest : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Unpack a .tar (already gunzipped) into `dir`. Enough of the format for an npm tarball:
+ * regular files and directories, with the long-name extensions npm uses.
+ */
+export function untar(buffer, dir) {
+  const text = (start, length) => buffer.toString('utf8', start, start + length).replace(/\0.*$/s, '');
+  let offset = 0;
+  let longName = null;
+  while (offset + 512 <= buffer.length) {
+    const name = text(offset, 100);
+    if (name === '') break; // two empty blocks end the archive
+    const size = parseInt(text(offset + 124, 12).trim() || '0', 8);
+    const type = text(offset + 156, 1) || '0';
+    const prefix = text(offset + 345, 155);
+    const body = buffer.subarray(offset + 512, offset + 512 + size);
+    offset += 512 + Math.ceil(size / 512) * 512;
+
+    if (type === 'x') {
+      // pax header: "<length> path=<name>\n"
+      const match = /\d+ path=([^\n]*)\n/.exec(body.toString('utf8'));
+      if (match) longName = match[1];
+      continue;
+    }
+    if (type === 'L') {
+      longName = body.toString('utf8').replace(/\0.*$/s, '');
+      continue;
+    }
+    if (type === 'g') continue;
+
+    const entry = longName ?? (prefix ? `${prefix}/${name}` : name);
+    longName = null;
+    const target = path.resolve(dir, entry);
+    // Nothing in the archive may land outside the folder it is unpacked into.
+    if (target !== path.resolve(dir) && !target.startsWith(path.resolve(dir) + path.sep)) continue;
+    if (type === '5') fs.mkdirSync(target, { recursive: true });
+    else if (type === '0' || type === '') {
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, body);
+    }
+  }
+}
+
+/**
+ * Download `version` from npm and run it with the same arguments. Returns its exit code,
+ * or null when it couldn't be fetched, in which case the caller carries on itself.
+ */
+export async function runVersion(version, args) {
+  const dir = path.join(os.tmpdir(), `create-nevela-${version}-${process.pid}`);
+  try {
+    const response = await fetch(`${REGISTRY}/-/create-nevela-${version}.tgz`, { signal: AbortSignal.timeout(30000) });
+    if (!response.ok) return null;
+    untar(zlib.gunzipSync(Buffer.from(await response.arrayBuffer())), dir);
+    const entry = path.join(dir, 'package', 'index.mjs');
+    if (!fs.existsSync(entry)) return null;
+
+    const result = spawnSync(process.execPath, [entry, ...args], {
+      stdio: 'inherit',
+      // The newer one must not go looking for a newer one in turn.
+      env: { ...process.env, NEVELA_NO_SELF_UPDATE: '1' },
+    });
+    return result.status ?? 1;
+  } catch {
+    return null;
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}

package/shell.mjs

@@ -0,0 +1,21 @@
+// Running other programs, the same way on every platform.
+
+import { spawnSync } from 'node:child_process';
+
+export const windows = process.platform === 'win32';
+
+// `^` is not in the safe list on purpose: unquoted, cmd.exe treats it as an escape
+// character and drops it, which turned the constraint "^0.1" into an exact "0.1".
+export const quote = (arg) => (/^[\w./:=@,-]+$/.test(arg) ? arg : `"${arg.replace(/"/g, '\\"')}"`);
+export const shellLine = (command, args) => [command, ...args.map(quote)].join(' ');
+
+/**
+ * .bat and .cmd shims (composer, pnpm, Herd's php) only resolve through a shell on
+ * Windows. That is also why `php` can be "not found" in Git Bash while this still finds
+ * it: Git Bash doesn't run php.bat for the bare name, and cmd.exe does. A shell takes one
+ * command string, so every argument is quoted here.
+ */
+export function spawnCommand(command, args, options) {
+  if (!windows) return spawnSync(command, args, options);
+  return spawnSync(shellLine(command, args), { ...options, shell: true });
+}

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/SetupCommand.php

@@ -0,0 +1,55 @@
+<?php
+
+namespace Nevela\Laravel\Console;
+
+use Illuminate\Console\Command;
+
+/**
+ * Everything a freshly installed app needs before it can be used, in one process.
+ *
+ * `create-nevela` runs this once. Done as separate artisan calls, each step pays for
+ * Laravel starting up again, which on Windows is a few seconds every time.
+ */
+final class SetupCommand extends Command
+{
+    protected $signature = 'nevela:setup
+        {--name= : Name for the starter account}
+        {--email= : Email for the starter account. Leave out to create no account}
+        {--password= : Password for the starter account}';
+
+    protected $description = 'Finish setting up a new app: key, Sanctum\'s migration, generated files, migrations and a starter account';
+
+    protected $hidden = true;
+
+    public function handle(): int
+    {
+        if (blank(config('app.key'))) {
+            $this->callSilently('key:generate', ['--force' => true]);
+        }
+        $this->callSilently('vendor:publish', ['--tag' => 'sanctum-migrations']);
+
+        // routes/nevela.php, the launcher, and the dashboard's (empty) resource registry.
+        if ($this->callSilently('nevela:generate') !== self::SUCCESS) {
+            $this->components->error('Could not write the generated files.');
+
+            return self::FAILURE;
+        }
+        if ($this->call('migrate', ['--force' => true]) !== self::SUCCESS) {
+            return self::FAILURE;
+        }
+
+        if ($this->option('email')) {
+            $status = $this->call('nevela:user', [
+                '--name' => $this->option('name') ?: 'Admin',
+                '--email' => $this->option('email'),
+                '--password' => $this->option('password'),
+            ]);
+            if ($status !== self::SUCCESS) {
+                // The app itself is fine; the installer says how to add an account by hand.
+                return 2;
+            }
+        }
+
+        return self::SUCCESS;
+    }
+}

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

@@ -0,0 +1,195 @@
+<?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\DashboardState;
+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 {
+            $state = DashboardState::read($web);
+            $row('Dashboard', $state->template !== null ? "template {$state->template}" : '<fg=gray>template version not recorded</>');
+
+            // What this app has made its own. An update leaves every one of these alone.
+            $changes = $state->yourChanges($web);
+            if ($changes === null) {
+                $row('Your dashboard changes', '<fg=gray>not tracked yet: php nevela update records them</>');
+            } else {
+                $count = count($changes['changed']) + count($changes['deleted']);
+                $row('Your dashboard changes', $count === 0 ? 'none' : "{$count} file(s), kept on every update");
+                if ($this->output->isVerbose()) {
+                    foreach ($changes['changed'] as $path) {
+                        $this->line("    <fg=gray>changed</> {$path}");
+                    }
+                    foreach ($changes['deleted'] as $path) {
+                        $this->line("    <fg=gray>deleted</> {$path}");
+                    }
+                } elseif ($count > 0) {
+                    $this->line('    <fg=gray>php nevela status -v lists them</>');
+                }
+            }
+            if ($last = end($state->history)) {
+                $row('Last dashboard update', "{$last['from']} → {$last['to']} on ".substr((string) ($last['at'] ?? ''), 0, 10));
+            }
+
+            // `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;
+    }
+}