create-nevela 0.7.1 → 0.9.1

package/template/laravel/src/NevelaServiceProvider.php

@@ -13,7 +13,11 @@ use Illuminate\Support\Facades\Route;
 use Illuminate\Support\ServiceProvider;
 use Nevela\Laravel\Access\Access;
 use Nevela\Laravel\Access\Permissions;
+use Nevela\Laravel\Console\AdoptCommand;
+use Nevela\Laravel\Console\BlogCommand;
 use Nevela\Laravel\Console\DevCommand;
+use Nevela\Laravel\Console\DigestCommand;
+use Nevela\Laravel\Console\DisposableCommand;
 use Nevela\Laravel\Console\GenerateCommand;
 use Nevela\Laravel\Console\MakeResourceCommand;
 use Nevela\Laravel\Console\SeedCommand;
@@ -28,10 +32,13 @@ use Nevela\Laravel\Http\Access\RolesAreSetUp;
 use Nevela\Laravel\Http\Access\RolesController;
 use Nevela\Laravel\Http\Access\UsersController;
 use Nevela\Laravel\Http\FlareErrors;
+use Nevela\Laravel\Http\FormsController;
 use Nevela\Laravel\Http\Auth\AccountController;
 use Nevela\Laravel\Http\Auth\SecurityController;
 use Nevela\Laravel\Http\Auth\SignInController;
+use Nevela\Laravel\Http\PublicThrottle;
 use Nevela\Laravel\Http\TokenController;
+use Nevela\Laravel\Http\ActionController;
 use Nevela\Laravel\Http\TrashController;
 use Nevela\Laravel\Http\UploadController;
 use Nevela\Laravel\Media\Uploads;
@@ -58,9 +65,9 @@ final class NevelaServiceProvider extends ServiceProvider
 
             $this->publishes([__DIR__.'/../config/nevela.php' => config_path('nevela.php')], 'nevela-config');
             $this->commands([
-                MakeResourceCommand::class, GenerateCommand::class, SeedCommand::class, UserCommand::class,
+                MakeResourceCommand::class, AdoptCommand::class, BlogCommand::class, GenerateCommand::class, SeedCommand::class, UserCommand::class,
                 UpdateCommand::class, DevCommand::class, StatusCommand::class, VersionCommand::class, SetupCommand::class,
-                TrashCommand::class,
+                TrashCommand::class, DigestCommand::class, DisposableCommand::class,
             ]);
 
             // What has been in the trash too long is removed each night, wherever the app's
@@ -68,6 +75,8 @@ final class NevelaServiceProvider extends ServiceProvider
             // happens whenever someone opens the trash.
             $this->callAfterResolving(Schedule::class, function (Schedule $schedule) {
                 $schedule->command(TrashCommand::class)->dailyAt('03:40')->withoutOverlapping();
+                // The notices to the owner that were held back in a busy hour, as one email.
+                $schedule->command(DigestCommand::class)->hourly()->withoutOverlapping();
             });
         }
 
@@ -172,12 +181,21 @@ final class NevelaServiceProvider extends ServiceProvider
             'app' => Nevela::fingerprint(),
         ]))->name('nevela.ping');
 
+        Route::aliasMiddleware('nevela.throttle', PublicThrottle::class);
+
+        // What a resource's "public" section opens: no sign-in, and each route its own throttle.
+        if (is_file($open = base_path('routes/nevela-public.php'))) {
+            Route::prefix(trim($prefix.'/public', '/'))->middleware('api')->name('nevela.public.')->group($open);
+        }
+
         // Stored files. Open, like any image on a website: the key is the secret.
         Route::prefix($prefix)->middleware('api')->get('_nevela/files/{path}', [UploadController::class, 'show'])
             ->where('path', '.*')->name('nevela.files.show');
 
         Route::prefix($prefix)->middleware(config('nevela.middleware', ['api', 'auth:sanctum']))->name('nevela.')->group(function () {
             Route::put('_nevela/uploads/{resource}/{field}', [UploadController::class, 'store'])->name('uploads.store');
+            // A private file: only for someone who may view the record it belongs to.
+            Route::get('_nevela/private/{slug}/{id}/{field}', [UploadController::class, 'download'])->name('private.show');
 
             // The image profiles, for a client that wants to know which renditions exist.
             Route::get('_nevela/profiles', fn () => response()->json([
@@ -192,6 +210,9 @@ final class NevelaServiceProvider extends ServiceProvider
             Route::delete('_nevela/trash/{slug}/{id}', [TrashController::class, 'destroy'])->name('trash.destroy');
             Route::delete('_nevela/trash/{slug}', [TrashController::class, 'empty'])->name('trash.empty');
 
+            // A public form, from the inside: what it checks and what it has turned away.
+            Route::get('_nevela/forms/{slug}', [FormsController::class, 'show'])->name('forms.show');
+
             // Users and roles, for whoever holds the permissions to manage them.
             Route::middleware(RolesAreSetUp::class)->group(function () {
                 Route::get('_nevela/users', [UsersController::class, 'index'])->name('users.index');
@@ -221,6 +242,10 @@ final class NevelaServiceProvider extends ServiceProvider
                 'data' => array_map(fn ($d) => $d->toArray(), Nevela::all()),
             ]))->name('resources');
 
+            // A resource's own actions: on one record, and on the list or a selection from it.
+            Route::post('{slug}/_actions/{action}', [ActionController::class, 'collection'])->name('actions.collection');
+            Route::post('{slug}/{id}/_actions/{action}', [ActionController::class, 'record'])->name('actions.record');
+
             if (is_file($routes = base_path('routes/nevela.php'))) {
                 require $routes;
             }

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

@@ -0,0 +1,168 @@
+<?php
+
+namespace Nevela\Laravel\Support;
+
+use Illuminate\Validation\Rule;
+use InvalidArgumentException;
+
+/**
+ * Something that can be done to a record, or to a resource as a whole, beyond creating,
+ * editing and deleting it: accept an application, send an announcement.
+ *
+ * The descriptor says what it is called, where its button goes and what it asks for.
+ * What it does is a class of the app's own, written once: App\Nevela\Actions\<Resource>\<Action>.
+ * Between the two, Nevela does the route, the permission, the checking and the button.
+ */
+final class Action
+{
+    /** Where its button is: on one record, or on the list as a whole. */
+    public const ON = ['record', 'collection'];
+
+    /** Names that already mean something for every resource. */
+    public const RESERVED = ['create', 'view', 'edit', 'delete', 'update', 'restore', 'list', 'read'];
+
+    /** What an action can ask for. A picture or a relation is a record's business, not a button's. */
+    public const KINDS = ['string', 'text', 'int', 'float', 'boolean', 'date', 'datetime', 'enum'];
+
+    /**
+     * @param  string  $name  camelCase, as in the descriptor and the address: accept, sendAnnouncement
+     * @param  string|null  $confirm  A question to ask before it runs
+     * @param  array<string, scalar|null>  $when  Field values a record must have for the action to apply to it
+     * @param  array<string, Field>  $fields  What it asks the person for, in a sheet
+     * @param  bool  $many  A record action that can also be run on a selection of rows
+     */
+    public function __construct(
+        public readonly string $name,
+        public readonly string $label,
+        public readonly string $on = 'record',
+        public readonly ?string $icon = null,
+        public readonly ?string $confirm = null,
+        public readonly array $when = [],
+        public readonly array $fields = [],
+        public readonly bool $many = false,
+    ) {
+        if (! preg_match('/^[a-z][A-Za-z0-9]*$/', $name)) {
+            throw new InvalidArgumentException("Action \"{$name}\" must be camelCase, e.g. accept or sendAnnouncement.");
+        }
+        if (in_array(Naming::snake($name), self::RESERVED, true)) {
+            throw new InvalidArgumentException("\"{$name}\" is something every resource does already. Call the action something else.");
+        }
+        if (! in_array($on, self::ON, true)) {
+            throw new InvalidArgumentException("Action \"{$name}\" is on \"{$on}\". Use record or collection.");
+        }
+        if ($on === 'collection' && ($when !== [] || $many)) {
+            throw new InvalidArgumentException("Action \"{$name}\" is on the collection, so it has no one record to check \"when\" against or to select.");
+        }
+        foreach ($when as $field => $value) {
+            if (! is_scalar($value) && $value !== null) {
+                throw new InvalidArgumentException("Action \"{$name}\": \"when\" compares \"{$field}\" with one value, or with null.");
+            }
+        }
+        foreach ($fields as $field) {
+            if (! in_array($field->kind, self::KINDS, true)) {
+                throw new InvalidArgumentException("Action \"{$name}\" can't ask for \"{$field->name}\": a {$field->kind} isn't something a button asks for. Use: ".implode(', ', self::KINDS).'.');
+            }
+        }
+    }
+
+    /** @param array<string, mixed> $data */
+    public static function fromArray(string $name, array $data): self
+    {
+        $fields = [];
+        foreach ((array) ($data['fields'] ?? []) as $key => $field) {
+            $fields[(string) $key] = Field::fromArray((string) $key, (array) $field);
+        }
+
+        return new self(
+            $name,
+            (string) ($data['label'] ?? Naming::humanize($name)),
+            (string) ($data['on'] ?? 'record'),
+            $data['icon'] ?? null,
+            $data['confirm'] ?? null,
+            (array) ($data['when'] ?? []),
+            $fields,
+            (bool) ($data['many'] ?? false),
+        );
+    }
+
+    /** @return array<string, mixed> */
+    public function toArray(): array
+    {
+        return array_filter([
+            'label' => $this->label,
+            'icon' => $this->icon,
+            'on' => $this->on,
+            'confirm' => $this->confirm,
+            'when' => $this->when ?: null,
+            'fields' => $this->fields ? array_map(fn (Field $f) => $f->toArray(), $this->fields) : null,
+            'many' => $this->many ?: null,
+        ], fn ($v) => $v !== null);
+    }
+
+    /** The second half of its permission: "send_announcement" in "newsletter_subscriptions.send_announcement". */
+    public function key(): string
+    {
+        return Naming::snake($this->name);
+    }
+
+    /** The class that does it, without its namespace: SendAnnouncement. */
+    public function className(): string
+    {
+        return Naming::pascal($this->name);
+    }
+
+    /**
+     * Whether it applies to a record with these values, by field name.
+     *
+     * @param  array<string, mixed>  $values
+     */
+    public function applies(array $values): bool
+    {
+        foreach ($this->when as $field => $wanted) {
+            $value = $values[$field] ?? null;
+            $same = match (true) {
+                $wanted === null => $value === null,
+                $value === null => false,
+                // A yes/no column comes back from some databases as 1 and 0.
+                is_bool($wanted) => (bool) $value === $wanted,
+                default => (string) $value === (string) $wanted,
+            };
+            if (! $same) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * The rules its fields are checked by: the ones a resource's field of the same kind has.
+     *
+     * @return array<string, list<mixed>>
+     */
+    public function rules(): array
+    {
+        $rules = [];
+        foreach ($this->fields as $field) {
+            $rules[$field->name] = [$field->required ? 'required' : 'nullable', ...match (true) {
+                $field->format === 'email' => ['email', 'max:'.($field->maxLength ?? 255)],
+                $field->format === 'url' => ['url', 'max:'.($field->maxLength ?? 2048)],
+                $field->format === 'tel' => ['string', 'max:'.($field->maxLength ?? 32)],
+                $field->format === 'slug' => ['string', 'alpha_dash', 'max:'.($field->maxLength ?? 255)],
+                $field->format === 'color' => ['string', 'regex:/^#[0-9a-fA-F]{6}$/'],
+                $field->kind === 'string' => ['string', 'max:'.($field->maxLength ?? 255)],
+                $field->kind === 'text' => ['string', 'max:'.($field->maxLength ?? 65535)],
+                $field->kind === 'int' && $field->format === 'percent' => ['integer', 'between:0,100'],
+                $field->kind === 'int' => ['integer'],
+                $field->kind === 'float' && $field->format === 'percent' => ['numeric', 'between:0,100'],
+                $field->kind === 'float' => ['numeric'],
+                $field->kind === 'boolean' => ['boolean'],
+                $field->kind === 'date' => ['date_format:Y-m-d'],
+                $field->kind === 'datetime' => ['date'],
+                $field->kind === 'enum' => [Rule::in($field->options)],
+            }];
+        }
+
+        return $rules;
+    }
+}

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

@@ -0,0 +1,352 @@
+<?php
+
+namespace Nevela\Laravel\Support;
+
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+use Illuminate\Support\Str;
+use InvalidArgumentException;
+
+/**
+ * A descriptor for a table that is already there, read from the table itself.
+ *
+ * `php artisan nevela:adopt posts` is for an app that had its tables before it had Nevela.
+ * Nothing about the table is changed by reading it, and what can't be said in a descriptor
+ * is left out of it and listed: a column Nevela doesn't know about stays in the table,
+ * untouched by the API, for the app's own code to use.
+ *
+ * Types are taken as they are and no tighter. An `email` column is adopted as a string,
+ * not as an email, because every value in it was valid when it was saved and a stricter
+ * rule would refuse to save an old record again. Tightening is for whoever knows the data.
+ */
+final class Adoption
+{
+    private const INTEGERS = ['tinyint', 'smallint', 'mediumint', 'int', 'integer', 'bigint', 'int2', 'int4', 'int8', 'serial', 'bigserial', 'year'];
+
+    private const DECIMALS = ['decimal', 'numeric', 'float', 'double', 'real', 'float4', 'float8', 'double precision', 'money'];
+
+    private const STRINGS = ['varchar', 'char', 'bpchar', 'nvarchar', 'nchar', 'character varying', 'character', 'string'];
+
+    private const DATETIMES = ['datetime', 'timestamp', 'timestamptz', 'datetime2', 'datetimeoffset', 'smalldatetime'];
+
+    /** Columns every resource has already, by another name. */
+    private const OWN = ['id', 'created_at', 'updated_at', 'deleted_at'];
+
+    /**
+     * @param  array<string, Field>  $fields  The fields, keyed by the column each was read from
+     * @param  list<array{column: string, why: string}>  $left  Columns that are not in the descriptor
+     * @param  list<string>  $notes  What whoever adopts the table should know
+     */
+    private function __construct(
+        public readonly Descriptor $descriptor,
+        public readonly array $fields,
+        public readonly array $left,
+        public readonly array $notes,
+    ) {}
+
+    /**
+     * Read a table from the database.
+     *
+     * @param  list<Descriptor>  $resources  The resources the app has: a foreign key to one of their tables is a relation
+     *
+     * @throws InvalidArgumentException when the table can't be a resource, with the reason
+     */
+    public static function of(string $table, array $resources = [], ?string $name = null, ?string $icon = null, ?string $group = null): self
+    {
+        if (! Schema::hasTable($table)) {
+            throw new InvalidArgumentException("There is no table called {$table}.");
+        }
+
+        $columns = Schema::getColumns($table);
+
+        return self::describe($table, $columns, Schema::getIndexes($table), Schema::getForeignKeys($table), $resources, $name, $icon, $group, self::longest($table, $columns));
+    }
+
+    /**
+     * The longest value in each string column that has no length of its own.
+     *
+     * PostgreSQL's `varchar` can be declared without one, and SQLite keeps none at all,
+     * so nothing about such a column says how long its values may be. The values do.
+     *
+     * @param  list<array<string, mixed>>  $columns
+     * @return array<string, int> by column
+     */
+    private static function longest(string $table, array $columns): array
+    {
+        $unbounded = [];
+        foreach ($columns as $column) {
+            if (in_array(strtolower((string) ($column['type_name'] ?? '')), self::STRINGS, true) && ! str_contains((string) ($column['type'] ?? ''), '(')) {
+                $unbounded[] = (string) $column['name'];
+            }
+        }
+        if ($unbounded === []) {
+            return [];
+        }
+        try {
+            $grammar = DB::connection()->getQueryGrammar();
+            $row = (array) DB::table($table)->selectRaw(implode(', ', array_map(fn (string $column) => 'max(length('.$grammar->wrap($column).')) as '.$grammar->wrap($column), $unbounded)))->first();
+        } catch (\Throwable) {
+            return []; // a database that measures some other way: the usual length, as for any string
+        }
+
+        return array_map(fn ($length) => (int) $length, $row);
+    }
+
+    /**
+     * The same, from what Laravel's schema builder says about a table: getColumns(),
+     * getIndexes() and getForeignKeys().
+     *
+     * @param  list<array<string, mixed>>  $columns
+     * @param  list<array<string, mixed>>  $indexes
+     * @param  list<array<string, mixed>>  $foreignKeys
+     * @param  list<Descriptor>  $resources
+     * @param  array<string, int>  $longest  The longest value in a string column that declares no length, by column
+     *
+     * @throws InvalidArgumentException
+     */
+    public static function describe(string $table, array $columns, array $indexes, array $foreignKeys, array $resources = [], ?string $name = null, ?string $icon = null, ?string $group = null, array $longest = []): self
+    {
+        $name = Naming::pascal($name ?? Str::singular($table));
+        $byName = [];
+        foreach ($columns as $column) {
+            $byName[(string) $column['name']] = $column;
+        }
+
+        $idType = self::idType($table, $byName, $indexes);
+        $missing = array_values(array_diff(['created_at', 'updated_at'], array_keys($byName)));
+        if ($missing !== []) {
+            throw new InvalidArgumentException("{$table} has no ".implode(' or ', $missing).'. Nevela sorts and counts records by when they were made and changed: add the columns with a migration ($table->timestamps()), then adopt it.');
+        }
+
+        $unique = [];
+        foreach ($indexes as $index) {
+            if (($index['unique'] ?? false) && ! ($index['primary'] ?? false) && count($index['columns'] ?? []) === 1) {
+                $unique[(string) $index['columns'][0]] = true;
+            }
+        }
+        // column => the table it points at, for a foreign key on that one column to an id.
+        $parents = [];
+        foreach ($foreignKeys as $key) {
+            if (count($key['columns'] ?? []) === 1 && ($key['foreign_columns'] ?? []) === ['id']) {
+                $parents[(string) $key['columns'][0]] = (string) $key['foreign_table'];
+            }
+        }
+        $tables = [$table => $name];
+        foreach ($resources as $resource) {
+            $tables[$resource->table] ??= $resource->name;
+        }
+
+        $fields = [];
+        $left = [];
+        $notes = [];
+        foreach ($byName as $column => $info) {
+            if (in_array($column, self::OWN, true)) {
+                continue;
+            }
+            $required = ! ($info['nullable'] ?? false);
+            $leave = function (string $why) use (&$left, &$notes, $column, $info, $required) {
+                $left[] = ['column' => $column, 'why' => $why];
+                if ($required && ($info['default'] ?? null) === null && ! ($info['auto_increment'] ?? false) && ($info['generation'] ?? null) === null) {
+                    $notes[] = "{$column} has to have a value and has no default, and it isn't in the descriptor, so creating a record from the dashboard will fail. Give the column a default, or make it nullable.";
+                }
+            };
+
+            $field = Naming::camel($column);
+            if (! preg_match('/^[a-z][A-Za-z0-9]*$/', $field) || Naming::snake($field) !== $column || in_array($field, Field::RESERVED, true)) {
+                $leave("its name can't be written as a field");
+
+                continue;
+            }
+            if (($info['generation'] ?? null) !== null) {
+                $leave('the database works it out');
+
+                continue;
+            }
+            if (preg_match('/(^|_)(password|secret|token)$/', $column)) {
+                $leave('it looks like a secret');
+
+                continue;
+            }
+
+            if (isset($parents[$column])) {
+                $target = $tables[$parents[$column]] ?? null;
+                if ($target !== null && str_ends_with($column, '_id')) {
+                    $fields[$column] = new Field($field, 'belongsTo', required: $required, unique: isset($unique[$column]), target: $target);
+
+                    continue;
+                }
+                $notes[] = $target === null
+                    ? "{$column} points at {$parents[$column]}, which isn't a resource, so it is adopted as a plain value. Adopt {$parents[$column]} first and it becomes a relation."
+                    : "{$column} points at {$parents[$column]}, but a relation's column ends in _id, so it is adopted as a plain value.";
+            }
+
+            $kind = self::kind($info);
+            if ($kind === null) {
+                $leave(strtolower((string) ($info['type_name'] ?? 'this type')).' has no field kind');
+
+                continue;
+            }
+            // No length of its own, and more in it already than the usual one allows.
+            if ($kind['kind'] === 'string' && ! isset($kind['maxLength']) && ($longest[$column] ?? 0) > 255) {
+                $kind['maxLength'] = max(65_535, $longest[$column]);
+                $notes[] = "{$column} declares no length and holds values longer than 255 characters, so it is adopted with room for ".number_format($kind['maxLength']).'.';
+            }
+            $default = isset($unique[$column]) ? null : self::default($kind, $info['default'] ?? null);
+            try {
+                $fields[$column] = new Field($field, $kind['kind'], required: $required, unique: isset($unique[$column]), options: $kind['options'] ?? [], maxLength: $kind['maxLength'] ?? null, default: $default);
+            } catch (InvalidArgumentException $e) {
+                $leave($e->getMessage());
+            }
+        }
+        if ($fields === []) {
+            throw new InvalidArgumentException("{$table} has no column that can be a field.");
+        }
+        // The app's own soft deletes become Nevela's trash, which doesn't keep things for ever.
+        if (isset($byName['deleted_at'])) {
+            $notes[] = "{$table} has a deleted_at column already, so the rows it marks as deleted are in Nevela's trash from the start, and the trash removes for good what has been in it longer than trash.days (30 unless you changed it). If those rows are to be kept, set trash.days to null in config/nevela.php before anyone opens the Trash page.";
+        }
+
+        $keyed = [];
+        foreach ($fields as $field) {
+            $keyed[$field->name] = $field;
+        }
+        $base = Descriptor::make($name, $keyed);
+
+        return new self(
+            new Descriptor($name, $keyed, $table, $base->slug, $base->label, $base->pluralLabel, $icon, $group, null, $idType, true),
+            $fields,
+            $left,
+            $notes,
+        );
+    }
+
+    /**
+     * What the table's ids are. A resource has one id column, called id, holding integers or UUIDs.
+     *
+     * @param  array<string, array<string, mixed>>  $columns
+     * @param  list<array<string, mixed>>  $indexes
+     */
+    private static function idType(string $table, array $columns, array $indexes): string
+    {
+        $primary = null;
+        foreach ($indexes as $index) {
+            if ($index['primary'] ?? false) {
+                $primary = array_values($index['columns'] ?? []);
+            }
+        }
+        $id = $columns['id'] ?? null;
+        if ($id === null || ($primary !== null && $primary !== ['id']) || ($primary === null && ! ($id['auto_increment'] ?? false))) {
+            throw new InvalidArgumentException("{$table} can't be a resource: a resource's primary key is one column called id.");
+        }
+        $type = strtolower((string) ($id['type_name'] ?? ''));
+        $full = strtolower((string) ($id['type'] ?? $type));
+
+        return match (true) {
+            in_array($type, self::INTEGERS, true) => 'int',
+            in_array($type, ['uuid', 'uniqueidentifier'], true), in_array($type, self::STRINGS, true) && str_contains($full, '(36)') => 'uuid',
+            default => throw new InvalidArgumentException("{$table} can't be a resource: its ids are neither integers nor UUIDs."),
+        };
+    }
+
+    /**
+     * The field kind a column is, or null when there isn't one for it.
+     *
+     * @param  array<string, mixed>  $column
+     * @return array{kind: string, maxLength?: int, options?: list<string>}|null
+     */
+    private static function kind(array $column): ?array
+    {
+        $type = strtolower((string) ($column['type_name'] ?? ''));
+        $full = strtolower((string) ($column['type'] ?? $type));
+        $length = preg_match('/\((\d+)\)/', $full, $m) ? (int) $m[1] : null;
+
+        return match (true) {
+            in_array($type, ['bool', 'boolean', 'bit'], true), $type === 'tinyint' && $length === 1 => ['kind' => 'boolean'],
+            in_array($type, self::INTEGERS, true) => ['kind' => 'int'],
+            in_array($type, self::DECIMALS, true) => ['kind' => 'float'],
+            $type === 'date' => ['kind' => 'date'],
+            in_array($type, self::DATETIMES, true) => ['kind' => 'datetime'],
+            // nvarchar(max) is SQL Server's long text.
+            in_array($type, self::STRINGS, true) && str_contains($full, '(max)') => ['kind' => 'text'],
+            // Its own length where it has one that isn't the usual: a value that fit the column has to fit the rule.
+            in_array($type, self::STRINGS, true) => ['kind' => 'string'] + ($length !== null && $length !== 255 ? ['maxLength' => $length] : []),
+            in_array($type, ['uuid', 'uniqueidentifier'], true) => ['kind' => 'string', 'maxLength' => 36],
+            $type === 'tinytext' => ['kind' => 'string'],
+            in_array($type, ['text', 'ntext'], true) => ['kind' => 'text'],
+            $type === 'mediumtext' => ['kind' => 'text', 'maxLength' => 16_777_215],
+            $type === 'longtext' => ['kind' => 'text', 'maxLength' => 4_294_967_295],
+            $type === 'enum' => self::choices((string) ($column['type'] ?? '')),
+            default => null,
+        };
+    }
+
+    /**
+     * A column's default, as the field's: 'pending', 0, false. Each database writes it its
+     * own way ('pending'::character varying), and one that is worked out when a row is
+     * made (CURRENT_TIMESTAMP, nextval(…)) is the column's business and is left there.
+     *
+     * @param  array{kind: string, options?: list<string>}  $kind
+     */
+    private static function default(array $kind, mixed $written): string|int|float|bool|null
+    {
+        if (! is_scalar($written) || (string) $written === '') {
+            return null;
+        }
+        $text = trim((string) $written);
+        // PostgreSQL adds what type it is; SQL Server wraps it in brackets.
+        $text = (string) preg_replace('/::[a-z_ ]+(\([0-9, ]*\))?(\[\])?$/i', '', $text);
+        while (str_starts_with($text, '(') && str_ends_with($text, ')')) {
+            $text = substr($text, 1, -1);
+        }
+        $quoted = strlen($text) >= 2 && $text[0] === "'" && str_ends_with($text, "'");
+        $value = $quoted ? str_replace("''", "'", substr($text, 1, -1)) : $text;
+        if (! $quoted && (strcasecmp($value, 'null') === 0 || preg_match('/[()]|^current_/i', $value))) {
+            return null;
+        }
+
+        return match ($kind['kind']) {
+            'string', 'text' => $value === '' ? null : $value,
+            'enum' => in_array($value, $kind['options'] ?? [], true) ? $value : null,
+            'int' => filter_var($value, FILTER_VALIDATE_INT) === false ? null : (int) $value,
+            'float' => is_numeric($value) ? (float) $value : null,
+            'boolean' => match (strtolower($value)) {
+                '1', 'true', 't' => true,
+                '0', 'false', 'f' => false,
+                default => null,
+            },
+            default => null,
+        };
+    }
+
+    /**
+     * A MySQL enum column: its values, where they are ones an enum field can have.
+     *
+     * @return array{kind: string, options?: list<string>}
+     */
+    private static function choices(string $type): array
+    {
+        preg_match_all("/'((?:[^']|'')*)'/", $type, $m);
+        $options = $m[1];
+        foreach ($options as $option) {
+            if (! preg_match('/^[A-Za-z0-9_-]+$/', $option)) {
+                return ['kind' => 'string'];
+            }
+        }
+
+        return $options === [] ? ['kind' => 'string'] : ['kind' => 'enum', 'options' => $options];
+    }
+
+    /** One field as it is written after --fields, e.g. "excerpt:string(500)?". */
+    public static function spec(Field $field): string
+    {
+        $type = match (true) {
+            $field->kind === 'belongsTo' => "belongsTo({$field->target})",
+            $field->kind === 'enum' => 'enum('.implode('|', $field->options).')',
+            $field->maxLength !== null => "{$field->kind}({$field->maxLength})",
+            default => $field->kind,
+        };
+        $default = $field->default === null ? '' : '='.(is_bool($field->default) ? ($field->default ? 'true' : 'false') : $field->default);
+
+        return $type.($field->required ? '' : '?').($field->unique ? '!' : '').$default;
+    }
+}