@flarum/cli 3.0.12 → 3.0.13

package/lib/steps/gen-ext-scaffolder.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.genExtScaffolder = exports.EXTENSION_MODULES = exports.EXTENSION_PARAMS = void 0;
+exports.genExtScaffolder = exports.EXTENSION_MODULES = exports.EXTENSION_PARAMS = exports.licenseTextFor = void 0;
 const tslib_1 = require("tslib");
 const scaffolder_1 = require("boilersmith/scaffolding/scaffolder");
 const chalk_1 = tslib_1.__importDefault(require("chalk"));
@@ -15,6 +15,17 @@ const string_1 = tslib_1.__importDefault(require("string"));
 function assertUnreachable(_x) {
     throw new Error("Didn't expect to get here");
 }
+/**
+ * The SPDX text for a licence, or an empty string when it isn't a known SPDX
+ * identifier (e.g. "proprietary" or a free-form "© Some Company").
+ */
+function licenseTextFor(licenseType) {
+    if (typeof licenseType !== 'string' || !licenseType)
+        return '';
+    const id = [...simple_1.default].find((l) => l.toLowerCase() === licenseType.toLowerCase());
+    return id ? require(`spdx-license-list/licenses/${id}`).licenseText : '';
+}
+exports.licenseTextFor = licenseTextFor;
 exports.EXTENSION_PARAMS = [
     'packageName',
     'packageDescription',
@@ -157,7 +168,7 @@ function paramNamesToDef(name) {
             return {
                 name,
                 uses: ['licenseType'],
-                compute: async (_paths, licenseType) => licenseType && licenseType !== 'proprietary' ? require(`spdx-license-list/licenses/${licenseType}`).licenseText : '',
+                compute: async (_paths, licenseType) => licenseTextFor(licenseType),
             };
         case 'extensionId':
             return {
@@ -609,11 +620,15 @@ function moduleNameToDef(name) {
                         'autoload-dev.psr-4.${params.packageNamespace}\\Tests\\',
                         'scripts.test',
                         'scripts.test:unit',
+                        'scripts.test:unit:filter',
                         'scripts.test:integration',
+                        'scripts.test:integration:filter',
                         'scripts.test:setup',
                         'scripts-descriptions.test',
                         'scripts-descriptions.test:unit',
+                        'scripts-descriptions.test:unit:filter',
                         'scripts-descriptions.test:integration',
+                        'scripts-descriptions.test:integration:filter',
                         'scripts-descriptions.test:setup',
                         'require-dev.flarum/testing',
                     ],

package/lib/steps/stubs/backend/advanced-api-resource.js

@@ -49,7 +49,7 @@ class GenerateAdvancedApiResourceStub extends php_base_1.BasePhpStubStep {
                     type: 'multiselect',
                     message: 'Endpoints',
                     choices: [
-                        { title: 'index', value: 'index', selected: true },
+                        { title: 'index', value: 'list', selected: true },
                         { title: 'show', value: 'show', selected: true },
                         { title: 'create', value: 'create', selected: true },
                         { title: 'update', value: 'update', selected: true },

package/lib/steps/stubs/backend/model-factory.d.ts

@@ -0,0 +1,24 @@
+import { Validator } from '../../../utils/validation';
+import { BasePhpStubStep } from '../php-base';
+/**
+ * The factory a model's tests fill it from. It sits next to the model, named
+ * after it, which is where Flarum looks for a model's factory.
+ */
+export declare class GenerateModelFactoryStub extends BasePhpStubStep {
+    type: string;
+    protected schema: {
+        recommendedSubdir: string;
+        sourceFile: string;
+        params: ({
+            name: string;
+            type: string;
+            message: string;
+            validate: typeof Validator.className;
+        } | {
+            name: string;
+            type: string;
+            message: string;
+            validate?: undefined;
+        })[];
+    };
+}

package/lib/steps/stubs/backend/model-factory.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GenerateModelFactoryStub = void 0;
+const validation_1 = require("../../../utils/validation");
+const php_base_1 = require("../php-base");
+/**
+ * The factory a model's tests fill it from. It sits next to the model, named
+ * after it, which is where Flarum looks for a model's factory.
+ */
+class GenerateModelFactoryStub extends php_base_1.BasePhpStubStep {
+    constructor() {
+        super(...arguments);
+        this.type = 'Generate Model Factory Class';
+        this.schema = {
+            recommendedSubdir: '',
+            sourceFile: 'backend/model-factory.php',
+            params: [
+                {
+                    name: 'className',
+                    type: 'text',
+                    message: 'Factory class name',
+                    validate: validation_1.Validator.className,
+                },
+                {
+                    name: 'classNamespace',
+                    type: 'text',
+                    message: 'Class Namespace',
+                },
+            ],
+        };
+    }
+}
+exports.GenerateModelFactoryStub = GenerateModelFactoryStub;

package/lib/steps/upgrade/twopointoh/backend/email-views.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 const ejs_1 = tslib_1.__importDefault(require("ejs"));
 const base_1 = require("../base");
+/** Where a view lives: `acme-thing::emails.launched` is in `.../emails/launched.blade.php`. */
+const viewFile = (view) => '/' + view.split('::').pop().replace(/\./g, '/') + '.blade.php';
 class EmailViews extends base_1.BaseUpgradeStep {
     constructor() {
         super(...arguments);
@@ -28,38 +30,28 @@ class EmailViews extends base_1.BaseUpgradeStep {
                 };
             },
             async (file, code) => {
-                if (Object.keys(this.collected).length === 0)
-                    return null;
-                const fileName = file.split('/').pop();
                 const newFiles = [];
-                Object.keys(this.collected).forEach((classFile) => {
-                    if (!this.collected[classFile]) {
-                        return;
-                    }
-                    if (!this.collected[classFile].html && !this.collected[classFile].text) {
-                        return;
+                for (const views of Object.values(this.collected)) {
+                    // A notification that has both views already has nothing to convert,
+                    // such as one already upgraded to 2.0.
+                    if (!views || Boolean(views.html) === Boolean(views.text))
+                        continue;
+                    const view = views.html || views.text;
+                    // The view's own file, by its full path: on 2.x the html and plain
+                    // views of a notification have the same file name.
+                    if (!file.endsWith(viewFile(view)))
+                        continue;
+                    const viewFileName = view.split('::')[1].split('.').pop();
+                    for (const viewType of ['text', 'html']) {
+                        const templateContent = this.fsEditor.read(__dirname + this.templates[viewType]);
+                        const viewTypePath = viewType === 'text' ? 'plain' : 'html';
+                        newFiles.push({
+                            path: file.split('/views/')[0] + '/views/email/' + viewTypePath + '/' + viewFileName + '.blade.php',
+                            code: ejs_1.default.render(templateContent, { content: code.trimEnd() }),
+                        });
                     }
-                    // if there is a text view but no html view, use the same content for both.
-                    // same for html view but no text view.
-                    ['text', 'html'].forEach((view) => {
-                        const viewType = view;
-                        const viewPath = this.collected[classFile][viewType] || this.collected[classFile][viewType === 'html' ? 'text' : 'html'];
-                        const viewFileName = viewPath.split('::')[1].split('.').pop();
-                        if (fileName === `${viewFileName}.blade.php`) {
-                            const templateContent = this.fsEditor.read(__dirname + this.templates[viewType]);
-                            const viewTypePath = viewType === 'text' ? 'plain' : 'html';
-                            newFiles.push({
-                                path: file.split('/views/')[0] + '/views/email/' + viewTypePath + '/' + viewFileName + '.blade.php',
-                                code: ejs_1.default.render(templateContent, { content: code.trimEnd() }),
-                            });
-                        }
-                    });
-                });
-                return {
-                    updated: code,
-                    delete: newFiles.length > 0,
-                    newFiles,
-                };
+                }
+                return newFiles.length > 0 ? { updated: code, delete: true, newFiles } : null;
             },
         ];
     }

package/lib/steps/upgrade/twopointoh/backend/extension-models.d.ts

@@ -0,0 +1,30 @@
+import { PhpProvider } from '../../../../providers/php-provider';
+export type ExtensionModel = {
+    file: string;
+    class: string;
+    table: string;
+    hasFactory: boolean;
+};
+export type Column = {
+    name: string;
+    type: string;
+    nullable: boolean;
+    autoIncrement: boolean;
+    references: string | null;
+    default?: {
+        value: unknown;
+    };
+    values?: string[];
+};
+/**
+ * The extension's models, each with its table, and the models that have, or
+ * are given, a factory, by table: core's and the extension's.
+ */
+export declare function extensionModels(root: string, php: PhpProvider): {
+    models: ExtensionModel[];
+    byTable: Record<string, string>;
+};
+/**
+ * The tables the extension's migrations leave, by name.
+ */
+export declare function migrationTables(root: string, php: PhpProvider): Record<string, Column[]>;

package/lib/steps/upgrade/twopointoh/backend/extension-models.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.migrationTables = exports.extensionModels = void 0;
+const tslib_1 = require("tslib");
+const fs_1 = tslib_1.__importDefault(require("fs"));
+const path_1 = tslib_1.__importDefault(require("path"));
+const globby_1 = tslib_1.__importDefault(require("globby"));
+const model_name_1 = require("../../../../utils/model-name");
+const read = (root, pattern) => Object.fromEntries(globby_1.default.sync(pattern, { cwd: root }).map((file) => [file, fs_1.default.readFileSync(path_1.default.join(root, file), 'utf8')]));
+/**
+ * The extension's models, each with its table, and the models that have, or
+ * are given, a factory, by table: core's and the extension's.
+ */
+function extensionModels(root, php) {
+    const result = php.run('upgrade.2-0.models', { data: { files: read(root, 'src/**/*.php') } });
+    // A model without $table has the one Eloquent names after its class.
+    const models = result.models.map((model) => {
+        var _a;
+        return (Object.assign(Object.assign({}, model), { table: (_a = model.table) !== null && _a !== void 0 ? _a : (0, model_name_1.pluralSnakeCaseModel)(model.class.split('\\').pop()) }));
+    });
+    return {
+        models,
+        byTable: Object.assign(Object.assign({}, result.core), Object.fromEntries(models.map((model) => [model.table, model.class]))),
+    };
+}
+exports.extensionModels = extensionModels;
+/**
+ * The tables the extension's migrations leave, by name.
+ */
+function migrationTables(root, php) {
+    const migrations = Object.fromEntries(Object.entries(read(root, 'migrations/*.php')).map(([file, code]) => [path_1.default.basename(file), code]));
+    return php.run('upgrade.2-0.migrations-schema', { data: { migrations } }).tables;
+}
+exports.migrationTables = migrationTables;

package/lib/steps/upgrade/twopointoh/backend/json-api.d.ts

@@ -7,6 +7,12 @@ export default class JsonApi extends BaseUpgradeStep {
     before(file: string, code: string, _advanced: AdvancedContent): void;
     replacements(file: string): Replacement[];
     targets(): string[];
+    /**
+     * 2.0's user resource has avatarSrcset next to avatarUrl, and browsers
+     * prefer it, so code that only sets the URL still shows a user's uploaded
+     * avatar on most screens.
+     */
+    flagAvatarUrl(): Replacement;
     gitCommit(): GitCommit;
     pauseMessage(): string;
 }

package/lib/steps/upgrade/twopointoh/backend/json-api.js

@@ -41,6 +41,7 @@ class JsonApi extends base_1.BaseUpgradeStep {
             return [];
         let collected = null;
         return [
+            this.flagAvatarUrl(),
             async (file, code) => {
                 const output = this.php.run('upgrade.2-0.json-api', { file, code });
                 collected = output.collected;
@@ -85,6 +86,19 @@ class JsonApi extends base_1.BaseUpgradeStep {
     targets() {
         return ['src/**/*', 'extend.php'];
     }
+    /**
+     * 2.0's user resource has avatarSrcset next to avatarUrl, and browsers
+     * prefer it, so code that only sets the URL still shows a user's uploaded
+     * avatar on most screens.
+     */
+    flagAvatarUrl() {
+        return (file, code) => {
+            if (/["']avatarUrl["']/.test(code)) {
+                this.leaveTodo(file, "It sets avatarUrl. 2.0's API also has avatarSrcset, which browsers prefer over the URL: set it too, or a user's uploaded avatar still shows.");
+            }
+            return null;
+        };
+    }
     gitCommit() {
         return {
             message: 'chore(2.0): JSON:API changes',

package/lib/steps/upgrade/twopointoh/backend/misc.d.ts

@@ -4,5 +4,11 @@ export default class MiscBackendChanges extends BaseUpgradeStep {
     replacements(file: string): Replacement[];
     targets(): string[];
     gitCommit(): GitCommit;
+    /**
+     * Since Laravel 11, changing a column drops every attribute the change
+     * leaves out, so a migration's ->change() must repeat the whole column
+     * definition. Only the author knows the column's full definition.
+     */
+    flagColumnChanges(): Replacement;
     pauseMessage(): string;
 }

package/lib/steps/upgrade/twopointoh/backend/misc.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 const base_1 = require("../base");
 const chalk_1 = tslib_1.__importDefault(require("chalk"));
+const MODIFYING_COLUMNS = 'https://laravel.com/docs/11.x/upgrade#modifying-columns';
 class MiscBackendChanges extends base_1.BaseUpgradeStep {
     constructor() {
         super(...arguments);
@@ -11,6 +12,9 @@ class MiscBackendChanges extends base_1.BaseUpgradeStep {
     replacements(file) {
         if (!file.endsWith('.php'))
             return [];
+        if (file.startsWith('migrations/')) {
+            return [this.flagColumnChanges()];
+        }
         return [
             (file, code) => ({
                 updated: this.php.run('upgrade.2-0.misc', { file, code }).code,
@@ -18,7 +22,7 @@ class MiscBackendChanges extends base_1.BaseUpgradeStep {
         ];
     }
     targets() {
-        return ['extend.php', 'src/**/*'];
+        return ['extend.php', 'src/**/*', 'migrations/**/*.php'];
     }
     gitCommit() {
         return {
@@ -26,17 +30,25 @@ class MiscBackendChanges extends base_1.BaseUpgradeStep {
             description: 'Miscellaneous backend changes',
         };
     }
+    /**
+     * Since Laravel 11, changing a column drops every attribute the change
+     * leaves out, so a migration's ->change() must repeat the whole column
+     * definition. Only the author knows the column's full definition.
+     */
+    flagColumnChanges() {
+        return (file, code) => {
+            if (/->\s*change\s*\(\s*\)/.test(code)) {
+                this.leaveTodo(file, `It changes a column with ->change(), which now drops every attribute the change leaves out: repeat the column's whole definition. ${MODIFYING_COLUMNS}`);
+            }
+            return null;
+        };
+    }
     pauseMessage() {
         const link = 'https://docs.flarum.org/2.x/extend/update-2_0#miscellaneous-1';
         const readMore = chalk_1.default.dim(`Read more: ${link}`);
-        const requiresManualChangeLink = 'https://laravel.com/docs/11.x/upgrade#modifying-columns';
         return `Various breaking backend changes have been made in 2.0. The tool has attempted to update your code accordingly.
                      Please review the changes and ensure everything is correct.
-                     ${readMore}
-
-                     Additionally, check every reference to a column definition change in your migrations, and make sure
-                     they are using the entire column definition. For more details, see:
-                     ${chalk_1.default.underline(requiresManualChangeLink)}`;
+                     ${readMore}`;
     }
 }
 exports.default = MiscBackendChanges;

package/lib/steps/upgrade/twopointoh/backend/model-factories.d.ts

@@ -0,0 +1,18 @@
+import { BaseUpgradeStep, GitCommit, Replacement } from '../base';
+/**
+ * Give each of the extension's models a factory, written from what its
+ * migrations say about the model's table, so that tests naming the model in
+ * prepareDatabase() need only give the columns they care about.
+ */
+export default class ModelFactories extends BaseUpgradeStep {
+    type: string;
+    /** The factories this step wrote. */
+    protected written: string[];
+    private extension;
+    replacements(file: string): Replacement[];
+    targets(): string[];
+    gitCommit(): GitCommit;
+    pauseMessage(): string;
+    addFactory(): Replacement;
+    private found;
+}

package/lib/steps/upgrade/twopointoh/backend/model-factories.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const chalk_1 = tslib_1.__importDefault(require("chalk"));
+const fs_1 = tslib_1.__importDefault(require("fs"));
+const path_1 = tslib_1.__importDefault(require("path"));
+const base_1 = require("../base");
+const extension_models_1 = require("./extension-models");
+/**
+ * Give each of the extension's models a factory, written from what its
+ * migrations say about the model's table, so that tests naming the model in
+ * prepareDatabase() need only give the columns they care about.
+ */
+class ModelFactories extends base_1.BaseUpgradeStep {
+    constructor() {
+        super(...arguments);
+        this.type = 'Model factories for tests';
+        /** The factories this step wrote. */
+        this.written = [];
+        this.extension = null;
+    }
+    replacements(file) {
+        return file.endsWith('.php') ? [this.addFactory()] : [];
+    }
+    targets() {
+        return ['src/**/*.php'];
+    }
+    gitCommit() {
+        return {
+            message: 'chore(2.0): model factories for tests',
+            description: "Flarum 2.0 tests take the columns they leave out from the model's factory.",
+        };
+    }
+    pauseMessage() {
+        const link = 'https://docs.flarum.org/2.x/extend/testing#model-factories';
+        return [
+            `Each model has a factory now. Written by this step: ${this.written.join(', ') || 'none'}.`,
+            'Tests that give prepareDatabase() a model class, rather than its table, take the columns they leave out from it.',
+            'Look for the @TODO comments on columns the migrations gave no default.',
+            chalk_1.default.underline(link),
+        ].join('\n                     ');
+    }
+    addFactory() {
+        return (file, code) => {
+            var _a;
+            const { models, byTable, tables } = this.found();
+            const model = models.find((candidate) => candidate.file === file);
+            if (!model)
+                return null;
+            const factory = path_1.default.posix.join(path_1.default.posix.dirname(file), `${model.class.split('\\').pop()}Factory.php`);
+            const hasFactoryClass = fs_1.default.existsSync(path_1.default.join(this.root, factory));
+            if (model.hasFactory && hasFactoryClass)
+                return null;
+            const result = this.php.run('upgrade.2-0.model-factory', {
+                file,
+                code,
+                data: { columns: (_a = tables[model.table]) !== null && _a !== void 0 ? _a : null, models: byTable },
+            });
+            // A factory the extension already has is its own.
+            if (hasFactoryClass) {
+                return { updated: result.code };
+            }
+            this.written.push(factory);
+            return { updated: result.code, newFiles: [{ path: factory, code: result.factory }] };
+        };
+    }
+    found() {
+        var _a;
+        (_a = this.extension) !== null && _a !== void 0 ? _a : (this.extension = Object.assign(Object.assign({}, (0, extension_models_1.extensionModels)(this.root, this.php)), { tables: (0, extension_models_1.migrationTables)(this.root, this.php) }));
+        return this.extension;
+    }
+}
+exports.default = ModelFactories;

package/lib/steps/upgrade/twopointoh/backend/phpunit.d.ts

@@ -1,6 +1,8 @@
 import { BaseUpgradeStep, GitCommit, Replacement } from '../base';
 export default class PhpUnit extends BaseUpgradeStep {
     type: string;
+    /** Core's models and the extension's, by table, for prepareDatabase() to name. */
+    private models;
     replacements(file: string): Replacement[];
     targets(): string[];
     gitCommit(): GitCommit;

package/lib/steps/upgrade/twopointoh/backend/phpunit.js

@@ -4,17 +4,24 @@ const tslib_1 = require("tslib");
 const base_1 = require("../base");
 const chalk_1 = tslib_1.__importDefault(require("chalk"));
 const phpunit_xml_1 = require("./phpunit-xml");
+const extension_models_1 = require("./extension-models");
 class PhpUnit extends base_1.BaseUpgradeStep {
     constructor() {
         super(...arguments);
-        this.type = 'PHPUnit 9 to 11 changes';
+        this.type = 'PHPUnit 9 to 12 changes';
+        /** Core's models and the extension's, by table, for prepareDatabase() to name. */
+        this.models = null;
     }
     replacements(file) {
         if (file.endsWith('.php')) {
             return [
-                (_file, code) => ({
-                    updated: this.php.run('upgrade.2-0.phpunit', { file, code }).code,
-                }),
+                (_file, code) => {
+                    var _a;
+                    (_a = this.models) !== null && _a !== void 0 ? _a : (this.models = (0, extension_models_1.extensionModels)(this.root, this.php).byTable);
+                    return {
+                        updated: this.php.run('upgrade.2-0.phpunit', { file, code, data: { models: this.models } }).code,
+                    };
+                },
             ];
         }
         // The XML rewrite previously sat behind the .php guard above (making it
@@ -34,18 +41,19 @@ class PhpUnit extends base_1.BaseUpgradeStep {
     }
     gitCommit() {
         return {
-            message: 'chore(2.0): Backend tests + PHPUnit 9 to 11 changes',
-            description: 'Flarum 2.0 uses PHPUnit 11 and encourages use of model factories for easier cross-database testing.',
+            message: 'chore(2.0): Backend tests + PHPUnit 9 to 12 changes',
+            description: 'Flarum 2.0 uses PHPUnit 12 and encourages use of model factories for easier cross-database testing.',
         };
     }
     pauseMessage() {
         const links = [
             'https://github.com/sebastianbergmann/phpunit/blob/9.6/DEPRECATIONS.md',
             'https://github.com/sebastianbergmann/phpunit/blob/10.5/DEPRECATIONS.md',
-            'https://github.com/sebastianbergmann/phpunit/blob/11.3.0/DEPRECATIONS.md',
+            'https://github.com/sebastianbergmann/phpunit/blob/11.5/DEPRECATIONS.md',
+            'https://github.com/sebastianbergmann/phpunit/blob/12.5/DEPRECATIONS.md',
         ];
         const dbLink = 'https://docs.flarum.org/2.x/extend/testing#model-factories';
-        return `Flarum 2.0 uses PHPUnit 11. The tool has applied the most significant changes, but you might still run into other deprecations.
+        return `Flarum 2.0 uses PHPUnit 12. The tool has applied the most significant changes, and left @TODO comments on what it could not, but you might still run into other deprecations.
                      Please refer to the following links for more information:
                      ${links.map((link) => chalk_1.default.underline(link)).join('\n                     ')}
 

package/lib/steps/upgrade/twopointoh/backend/search.d.ts

@@ -21,6 +21,15 @@ export default class Search extends BaseUpgradeStep {
     protected searchers: Record<string, string>;
     before(file: string, code: string, _advanced: AdvancedContent): void;
     replacements(_file: string): Replacement[];
+    /**
+     * The translations a gambit's stub uses: its key, and a key-value gambit's
+     * hint, which the search shows beside it. Only the author can say what the
+     * hint should be, so it is left for them to write.
+     */
+    gambitTranslations(gambit: Gambit): {
+        key: string;
+        value: string;
+    }[];
     targets(): string[];
     gitCommit(): GitCommit;
     pauseMessage(): string;

package/lib/steps/upgrade/twopointoh/backend/search.js

@@ -9,6 +9,10 @@ const gambit_1 = require("../../../stubs/frontend/gambit");
 const search_gambit_1 = require("../../../js/search-gambit");
 const base_2 = require("../../../locale/base");
 const model_name_1 = require("../../../../utils/model-name");
+const fs_1 = tslib_1.__importDefault(require("fs"));
+const path_1 = tslib_1.__importDefault(require("path"));
+/** A gambit with an is: pattern, such as is:private, rather than a key and value. */
+const isBoolean = (gambit) => gambit.pattern.includes('is:');
 class Search extends base_1.BaseUpgradeStep {
     constructor() {
         super(...arguments);
@@ -116,10 +120,6 @@ class Search extends base_1.BaseUpgradeStep {
                 if (this.gambits.length > 0 && Object.keys(((_a = this.data.collectedData.extendData) === null || _a === void 0 ? void 0 : _a.searchers) || {}).length > 0) {
                     const result = await this.command.runSteps(new step_manager_1.StepManager().silentGroup((steps) => {
                         this.gambits.forEach((gambit, index) => {
-                            let gambitKey = gambit.pattern.replace('is:', '');
-                            if (gambitKey.includes(':')) {
-                                gambitKey = gambitKey.split(':')[0];
-                            }
                             const relatedSearcher = Object.keys(this.data.collectedData.extendData.searchers).find((searcher) => {
                                 const filters = this.data.collectedData.extendData.searchers[searcher].filters || [];
                                 return filters.some((filter) => {
@@ -130,11 +130,11 @@ class Search extends base_1.BaseUpgradeStep {
                             if (relatedSearcher) {
                                 type = (0, model_name_1.pluralKebabCaseModel)(relatedSearcher.split('\\').pop().replace('Searcher', ''));
                             }
-                            steps
+                            const gambitSteps = steps
                                 .namedStep(`gambit-${index}`, new gambit_1.GenerateGambitStub(this.command.STUB_PATH, (0, gen_ext_scaffolder_1.genExtScaffolder)()), {}, [], {
                                 frontend: 'common',
                                 className: gambit.name,
-                                type: gambit.pattern.includes('is:') ? 'boolean' : 'key-value',
+                                type: isBoolean(gambit) ? 'boolean' : 'key-value',
                                 filterKey: gambit.filterKey,
                             })
                                 .step(new search_gambit_1.GenerateSearchGambitExtender(), {}, [
@@ -146,10 +146,9 @@ class Search extends base_1.BaseUpgradeStep {
                             ], {
                                 frontend: 'common',
                                 modelType: type,
-                            })
-                                .step(new base_2.LocaleStep((0, gen_ext_scaffolder_1.genExtScaffolder)()), {}, [], {
-                                key: `lib.gambits.${gambit.filterKey}.key`,
-                                value: gambitKey,
+                            });
+                            this.gambitTranslations(gambit).forEach((translation) => {
+                                gambitSteps.step(new base_2.LocaleStep((0, gen_ext_scaffolder_1.genExtScaffolder)()), {}, [], translation);
                             });
                             delete this.gambits[index];
                         });
@@ -171,6 +170,25 @@ class Search extends base_1.BaseUpgradeStep {
             },
         ];
     }
+    /**
+     * The translations a gambit's stub uses: its key, and a key-value gambit's
+     * hint, which the search shows beside it. Only the author can say what the
+     * hint should be, so it is left for them to write.
+     */
+    gambitTranslations(gambit) {
+        let gambitKey = gambit.pattern.replace('is:', '');
+        if (gambitKey.includes(':')) {
+            gambitKey = gambitKey.split(':')[0];
+        }
+        const translations = [{ key: `lib.gambits.${gambit.filterKey}.key`, value: gambitKey }];
+        if (!isBoolean(gambit)) {
+            const hint = `lib.gambits.${gambit.filterKey}.hint`;
+            const locale = fs_1.default.existsSync(path_1.default.join(this.root, 'resources/locale/en.yml')) ? 'resources/locale/en.yml' : 'locale/en.yml';
+            translations.push({ key: hint, value: gambitKey });
+            this.leaveTodo(locale, `describe what the ${gambitKey} gambit takes in ${hint}, which the search shows beside it.`);
+        }
+        return translations;
+    }
     targets() {
         return ['src/**/*', 'extend.php'];
     }