@flarum/cli 3.0.12 → 3.0.13

package/README.md

@@ -49,7 +49,7 @@ $ npm install -g @flarum/cli
 $ flarum-cli COMMAND
 running command...
 $ flarum-cli (-v|--version|version)
-@flarum/cli/3.0.12 darwin-arm64 node-v26.6.0
+@flarum/cli/3.0.13 darwin-arm64 node-v26.11.1
 $ flarum-cli --help [COMMAND]
 USAGE
   $ flarum-cli COMMAND
@@ -132,6 +132,38 @@ The CLI has different types of commands for different tasks:
 **Code Updates**: These commands help update extensions for newer versions of Flarum.
 
 - `flarum-cli update js-imports [PATH]`: Adds admin/forum/common namespaces to all JS imports from flarum core.
+- `flarum-cli upgrade 2.0 [PATH] [-n|--no-interaction] [--json] [--check] [--step <number>] [--force-steps]`: Upgrades a 1.x extension to Flarum 2.0, one step at a time, committing each step. Steps already committed are skipped, so running it again resumes where it stopped.
+
+To drive the upgrade from another program, such as an AI agent, pass `--json`. It asks nothing, and prints a single JSON object when it finishes. It exits non-zero when the upgrade didn't complete:
+
+```json
+{
+  "status": "failed",
+  "error": "1 file could not be upgraded by this step, so it made no changes. …",
+  "messages": [],
+  "steps": [
+    {
+      "step": 13,
+      "title": "Prepare for JSON:API changes.",
+      "status": "committed",
+      "commit": { "sha": "c63dd501…", "message": "chore(2.0): JSON:API changes" },
+      "notes": "Flarum 2.0 completely refactors the JSON:API implementation. …",
+      "todos": [{ "file": "extend.php", "line": 33, "text": "// @TODO: Replace with the new implementation …" }]
+    },
+    {
+      "step": 14,
+      "title": "Intervention Image Library v3",
+      "status": "failed",
+      "failures": [{ "file": "src/Thumbnailer.php", "reason": "Syntax error, unexpected '{' on line 15" }]
+    },
+    { "step": 15, "title": "Search & Filter API changes", "status": "not-run" }
+  ]
+}
+```
+
+Each step is `committed`, `no-changes`, `skipped` (committed by an earlier run), `failed` or `not-run`. A step that fails on some files lists them and makes no changes, so fix those files, commit, and run the command again. The `todos` are what the upgrade could not change itself: the `@TODO` comments the step's commit added, and work it can only point out, such as a file to add, which has a `line` of `null`. A `no-changes` step lists its `todos` too, when it has any.
+
+To see what the upgrade would change without changing anything, pass `--check`, such as for an extension already on Flarum 2.0. The steps run on the extension's last commit, in a temporary git worktree that is removed afterwards, and none is skipped. With `--json`, a step that would change something is `would-change`, with the `files` and `diff` of the change, and the report's `check` names the commit checked and whether changes not yet committed were left out.
 
 _And of course, you can always use the help command to see a list of all available commands with their descriptions:_
 

package/boilerplate/skeleton/extension/composer.json

@@ -49,7 +49,9 @@
             "@test:integration"
         ],
         "test:unit": "phpunit -c tests/phpunit.unit.xml",
+        "test:unit:filter": "phpunit -c tests/phpunit.unit.xml --filter",
         "test:integration": "phpunit -c tests/phpunit.integration.xml",
+        "test:integration:filter": "phpunit -c tests/phpunit.integration.xml --filter",
         "test:setup": "@php tests/integration/setup.php",
         "analyse:phpstan": "phpstan analyse",
         "clear-cache:phpstan": "phpstan clear-result-cache"
@@ -57,7 +59,9 @@
     "scripts-descriptions": {
         "test": "Runs all tests.",
         "test:unit": "Runs all unit tests.",
+        "test:unit:filter": "Runs unit tests whose name matches: composer test:unit:filter -- ClassName",
         "test:integration": "Runs all integration tests.",
+        "test:integration:filter": "Runs integration tests whose name matches: composer test:integration:filter -- ClassName",
         "test:setup": "Sets up a database for use with integration tests. Execute this only once.",
         "analyse:phpstan": "Run static analysis"
     },

package/boilerplate/skeleton/extension/js/package.json

@@ -10,11 +10,11 @@
     "@flarum/jest-config": "^2.0.0",
     "@flarum/prettier-config": "^1.0.0",
     "flarum-tsconfig": "^2.0.0",
-    "flarum-webpack-config": "^3.0.0",
+    "flarum-webpack-config": "^3.0.7",
     "prettier": "^2.5.1",
-    "typescript": "^4.5.4",
+    "typescript": "^4.9.5",
     "typescript-coverage-report": "^0.6.1",
-    "webpack": "^5.65.0",
+    "webpack": "^5.104.1",
     "webpack-cli": "^4.9.1"
   },
   "scripts": {
@@ -25,7 +25,7 @@
     "format-check": "prettier --check src",
     "clean-typings": "npx rimraf dist-typings && mkdir dist-typings",
     "build-typings": "<%= params.jsPackageManager %> run clean-typings && ([ -e src/@types ] && cp -r src/@types dist-typings/@types || true) && tsc && <%= params.jsPackageManager %> run post-build-typings",
-    "post-build-typings": "find dist-typings -type f -name '*.d.ts' -print0 | xargs -0 sed -i 's,../src/@types,@types,g'",
+    "post-build-typings": "find dist-typings -type f -name '*.d.ts' -print0 | xargs -0 sed -i.bak 's,../src/@types,@types,g' && find dist-typings -type f -name '*.d.ts.bak' -delete",
     "check-typings": "tsc --noEmit --emitDeclarationOnly false",
     "check-typings-coverage": "typescript-coverage-report",
     "test": "yarn node --experimental-vm-modules $(yarn bin jest)"

package/boilerplate/skeleton/extension/js/tsconfig.json

@@ -12,6 +12,9 @@
       "@types/**/*"
 ],
   "compilerOptions": {
+    // Only load the type packages the code imports. Others, such as the
+    // @types/node webpack brings along, use syntax TypeScript 4.9 can't read.
+    "types": [],
     // This will output typings to `dist-typings`
     "declarationDir": "./dist-typings",
     "baseUrl": ".",

package/boilerplate/skeleton/extension/js/tsconfig.test.json

@@ -3,6 +3,7 @@
     "include": ["tests/**/*"],
     "files": ["../../../node_modules/@flarum/jest-config/shims.d.ts"],
     "compilerOptions": {
+        "types": ["jest"],
         "strict": false,
         "noImplicitReturns": false,
         "noImplicitAny": false

package/boilerplate/stubs/backend/advanced-api-resource.php

@@ -14,7 +14,7 @@ use Tobyz\JsonApiServer\Context as OriginalContext;
 /**
  * @extends <% if (modelClassName) { %>Resource\AbstractDatabaseResource<<%= modelClassName %>><% } else { %>Resource\AbstractResource<object><% } %>
  */
-class <%= className %> extends <% if (modelClassName) { %>Resource\AbstractDatabaseResource<% } else { %>Resource\AbstractResource<% if (interfaces.length > 0) %> implements <%= interfaces.join(', ') %><% } %>
+class <%= className %> extends <% if (modelClassName) { %>Resource\AbstractDatabaseResource<% } else { %>Resource\AbstractResource<% if (interfaces.length > 0) { %> implements <%= interfaces.join(', ') %><% } %><% } %>
 {
     public function type(): string
     {
@@ -35,7 +35,7 @@ class <%= className %> extends <% if (modelClassName) { %>Resource\AbstractDatab
     {
         return [<% if (endpoints.includes('create')) { %>
             Endpoint\Create::make()<% if (modelClassName) { %>
-                ->can('create<%= modelClassName %>'),<% } %><% } %><% if (endpoints.includes('update')) { %>
+                ->can('create<%= modelClassName %>')<% } %>,<% } %><% if (endpoints.includes('update')) { %>
             Endpoint\Update::make()
                 ->can('update'),<% } %><% if (endpoints.includes('delete')) { %>
             Endpoint\Delete::make()
@@ -52,7 +52,7 @@ class <%= className %> extends <% if (modelClassName) { %>Resource\AbstractDatab
         return [
 
             /**
-             * @todo migrate logic from old serializer and controllers to this API Resource.
+             * @TODO migrate logic from old serializer and controllers to this API Resource.
              * @see https://docs.flarum.org/2.x/extend/api#api-resources
              */
 

package/boilerplate/stubs/backend/model-factory.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace <%= classNamespace %>;
+
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+class <%= className %> extends Factory
+{
+    // A default for each column, so tests only need to set the ones they care about.
+    // See https://docs.flarum.org/2.x/extend/testing#model-factories for more information.
+    public function definition(): array
+    {
+        return [
+            //
+        ];
+    }
+}

package/boilerplate/stubs/backend/model.php

@@ -5,9 +5,12 @@ namespace <%= classNamespace %>;
 use Flarum\Database\AbstractModel;
 use Flarum\Database\ScopeVisibilityTrait;
 use Flarum\Foundation\EventGeneratorTrait;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
 
 class <%= className %> extends AbstractModel
 {
+    use HasFactory;
+
     // See https://docs.flarum.org/2.x/extend/models.html#backend-models for more information.
     <% if (tableName) { %>
     protected $table = '<%= tableName %>';<% } %>

package/lib/base-command.d.ts

@@ -1,5 +1,5 @@
 import { Command, Interfaces } from '@oclif/core';
-import { IO } from 'boilersmith/io';
+import { IO, Message } from 'boilersmith/io';
 import { StepManager } from 'boilersmith/step-manager';
 import { FlarumProviders } from './providers';
 export declare enum LocationType {
@@ -20,19 +20,37 @@ export default abstract class BaseCommand extends Command {
     protected skipFinalMessage: boolean;
     runSteps(steps: StepManager<FlarumProviders>): Promise<{
         succeeded: true;
-        messages: import("boilersmith/io").Message[];
+        messages: Message[];
         stepsRan: string[];
     } | {
         succeeded: false;
         error: string;
         errorTrace?: string | undefined;
-        messages: import("boilersmith/io").Message[];
+        messages: Message[];
         stepsRan: string[];
         e?: any;
     }>;
+    /**
+     * Where the steps run, which is where the command was asked to unless a
+     * command runs them somewhere else.
+     */
+    protected stepsPath(path: string | undefined): string | undefined;
     extRoot(path: string | undefined): Promise<string>;
     run(): Promise<void>;
     protected welcomeMessage(): string;
+    /**
+     * The result of a run with `--json`, for the program that started it.
+     */
+    protected jsonReport(succeeded: boolean, error: string | null, messages: Message[]): Record<string, unknown>;
+    /**
+     * Written by hand rather than returned from `run()`: oclif colours JSON it
+     * prints itself whenever the output is a terminal.
+     */
+    protected writeJson(report: Record<string, unknown>): void;
+    /**
+     * With `--json`, an error before or between steps is still reported as JSON.
+     */
+    catch(err: any): Promise<any>;
     protected goodbyeMessage(): string;
     protected additionalPreRunChecks(_extRoot: string): Promise<void>;
     protected abstract steps(stepManager: StepManager<FlarumProviders>, extRoot: string): StepManager<FlarumProviders>;

package/lib/base-command.js

@@ -16,6 +16,7 @@ const chalk_1 = tslib_1.__importDefault(require("chalk"));
 const errors_1 = require("@oclif/errors");
 const monorepo_1 = require("./utils/monorepo");
 const mem_fs_1 = require("mem-fs");
+const terminal_1 = require("./utils/terminal");
 var LocationType;
 (function (LocationType) {
     LocationType[LocationType["FLARUM_EXTENSION"] = 0] = "FLARUM_EXTENSION";
@@ -34,7 +35,7 @@ class BaseCommand extends core_1.Command {
     async runSteps(steps) {
         const { args } = await this.parse(this.constructor);
         this.args = args;
-        const path = args.path;
+        const path = this.stepsPath(args.path);
         const paths = new paths_1.NodePaths({
             requestedDir: path,
             package: await this.extRoot(path),
@@ -42,6 +43,13 @@ class BaseCommand extends core_1.Command {
         const phpProvider = new php_provider_1.PhpSubsystemProvider((0, path_1.resolve)(__dirname, '../php-subsystem/index.php'));
         return steps.run(paths, this.genIO(), { php: phpProvider }, this.dry, args);
     }
+    /**
+     * Where the steps run, which is where the command was asked to unless a
+     * command runs them somewhere else.
+     */
+    stepsPath(path) {
+        return path;
+    }
     async extRoot(path) {
         let extRoot;
         if (this.requireExistingExtension) {
@@ -56,7 +64,7 @@ class BaseCommand extends core_1.Command {
         return extRoot;
     }
     async run() {
-        var _a;
+        var _a, _b, _c;
         const { args, flags } = await this.parse(this.constructor);
         this.args = args;
         this.flags = flags;
@@ -70,6 +78,14 @@ class BaseCommand extends core_1.Command {
         await this.additionalPreRunChecks(extRoot);
         const out = await this.runSteps(this.steps(new step_manager_1.StepManager(), extRoot));
         const errorMessages = out.messages.filter((m) => m.type === 'error');
+        if (this.jsonEnabled()) {
+            const succeeded = out.succeeded && errorMessages.length === 0;
+            const error = out.succeeded ? (_b = (_a = errorMessages[0]) === null || _a === void 0 ? void 0 : _a.message) !== null && _b !== void 0 ? _b : null : out.error;
+            this.writeJson(this.jsonReport(succeeded, error, out.messages));
+            if (!succeeded)
+                process.exitCode = 1;
+            return;
+        }
         // this.log('\n\n');
         if (!this.skipFinalMessage && out.succeeded && errorMessages.length === 0) {
             this.log(chalk_1.default.bold(chalk_1.default.underline(chalk_1.default.green('Success! The following steps were completed:'))));
@@ -88,12 +104,12 @@ class BaseCommand extends core_1.Command {
             }
         }
         else if (!out.succeeded) {
-            const prettyPrint = ((_a = out.e) === null || _a === void 0 ? void 0 : _a.code) === 'FL_ERR';
+            const prettyPrint = ((_c = out.e) === null || _c === void 0 ? void 0 : _c.code) === 'FL_ERR';
             if (!prettyPrint)
                 this.log(chalk_1.default.bold(chalk_1.default.underline(chalk_1.default.red('Error occurred, and could not complete:'))));
             if (prettyPrint) {
                 this.log('\n');
-                this.log('\u001B[A     => ' + chalk_1.default.bgRed.bold('   ERROR   ') + ' ' + chalk_1.default.red(out.error));
+                this.log((0, terminal_1.overwrite)() + '     => ' + chalk_1.default.bgRed.bold('   ERROR   ') + ' ' + chalk_1.default.red(out.error));
             }
             else {
                 this.log(chalk_1.default.red(out.error));
@@ -130,6 +146,36 @@ class BaseCommand extends core_1.Command {
     welcomeMessage() {
         return '';
     }
+    /**
+     * The result of a run with `--json`, for the program that started it.
+     */
+    jsonReport(succeeded, error, messages) {
+        return {
+            status: succeeded ? 'succeeded' : 'failed',
+            error: error === null ? null : (0, terminal_1.stripAnsi)(error),
+            messages: messages.map((m) => (Object.assign(Object.assign({}, m), { message: (0, terminal_1.stripAnsi)(m.message) }))),
+        };
+    }
+    /**
+     * Written by hand rather than returned from `run()`: oclif colours JSON it
+     * prints itself whenever the output is a terminal.
+     */
+    writeJson(report) {
+        process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    }
+    /**
+     * With `--json`, an error before or between steps is still reported as JSON.
+     */
+    async catch(err) {
+        var _a, _b, _c;
+        if (!this.jsonEnabled())
+            return super.catch(err);
+        const code = (_b = (_a = err === null || err === void 0 ? void 0 : err.oclif) === null || _a === void 0 ? void 0 : _a.exit) !== null && _b !== void 0 ? _b : 1;
+        if (code === 0)
+            return;
+        process.exitCode = code;
+        this.writeJson(this.jsonReport(false, (_c = err === null || err === void 0 ? void 0 : err.message) !== null && _c !== void 0 ? _c : String(err), []));
+    }
     goodbyeMessage() {
         return 'Please make sure to check my work, adjust formatting, and test before committing!!!';
     }
@@ -140,7 +186,8 @@ class BaseCommand extends core_1.Command {
     // Confirmation
     // ----------------------------------------------------------------
     genIO() {
-        return new io_1.PromptsIO(this.args, [], this.flags['no-interaction'], errors_1.exit);
+        // Nobody can answer a prompt when a program is reading the output.
+        return new io_1.PromptsIO(this.args, [], this.flags['no-interaction'] || this.jsonEnabled(), errors_1.exit);
     }
     monorepoPaths(options) {
         var _a, _b;

package/lib/commands/make/backend/model.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 const base_command_1 = tslib_1.__importDefault(require("../../../base-command"));
 const model_1 = require("../../../steps/stubs/backend/model");
+const model_factory_1 = require("../../../steps/stubs/backend/model-factory");
 const migration_1 = require("../../../steps/stubs/backend/migration");
 const api_resource_1 = require("../../../steps/stubs/backend/api-resource");
 const policy_1 = require("../../../steps/stubs/backend/policy");
@@ -16,8 +17,17 @@ class BackendModel extends base_command_1.default {
         });
     }
     static steps(stepManager, STUB_PATH, shouldRun, dependencies, predefinedDependencies) {
+        // The factory is not optional: the model uses HasFactory, which needs it.
         return stepManager
             .namedStep('backendModel', new model_1.GenerateModelStub(STUB_PATH, (0, gen_ext_scaffolder_1.genExtScaffolder)()), shouldRun, dependencies, predefinedDependencies)
+            .step(new model_factory_1.GenerateModelFactoryStub(STUB_PATH, (0, gen_ext_scaffolder_1.genExtScaffolder)()), {}, [
+            {
+                sourceStep: 'backendModel',
+                exposedName: 'className',
+                consumedName: 'className',
+                modifier: (modelClassName) => `${modelClassName}Factory`,
+            },
+        ])
             .step(new migration_1.GenerateMigrationStub(STUB_PATH, (0, gen_ext_scaffolder_1.genExtScaffolder)()), { optional: true, confirmationMessage: 'Generate corresponding Migration?', default: true }, [
             {
                 sourceStep: 'backendModel',

package/lib/commands/upgrade/2.0.d.ts

@@ -1,17 +1,60 @@
 import { StepManager } from 'boilersmith/step-manager';
 import BaseCommand from '../../base-command';
 import { FlarumProviders } from '../../providers';
+import { BaseUpgradeStep } from '../../steps/upgrade/twopointoh/base';
+import { IO, Message } from 'boilersmith/io';
+/**
+ * The temporary worktree a check runs the steps in, so the extension itself
+ * is never changed.
+ */
+type Checkout = {
+    /** The repository the extension is in. */
+    repo: string;
+    worktree: string;
+    branch: string;
+    /** The extension's root inside the worktree. */
+    root: string;
+    /** What was checked. */
+    commit: string;
+    /** Whether the extension had changes not committed, which a check leaves out. */
+    dirty: boolean;
+    cwd: string;
+};
 export default class TwoPointOh extends BaseCommand {
     static description: string;
+    static enableJsonFlag: boolean;
     static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
         step: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined>;
         'force-steps': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        check: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
     };
     static args: import("@oclif/core/lib/interfaces").Arg<any>[];
     protected requireExistingExtension: boolean;
     skipFinalMessage: boolean;
+    /**
+     * The steps this run was asked to take, in order.
+     */
+    protected scheduled: BaseUpgradeStep[];
+    protected checkout: Checkout | null;
+    run(): Promise<void>;
+    protected additionalPreRunChecks(extRoot: string): Promise<void>;
+    protected stepsPath(requested: string | undefined): string | undefined;
+    protected genIO(): IO;
+    protected createCheckout(extRoot: string): Promise<Checkout>;
+    /** Remove the worktree and its branch, saying so if it can't. */
+    protected removeCheckout(): Promise<void>;
+    /** What a step that committed in the worktree would change, from its commit. */
+    protected wouldChange(sha: string): {
+        files: string[];
+        diff: string;
+    };
     protected steps(steps: StepManager<FlarumProviders>, extRoot: string): StepManager<FlarumProviders>;
     private prepareSteps;
+    protected jsonReport(succeeded: boolean, error: string | null, messages: Message[]): Record<string, unknown>;
+    /** A step's outcome, as what it would change when checking. */
+    protected reported(step: BaseUpgradeStep): Record<string, unknown>;
     protected welcomeMessage(): string;
     protected goodbyeMessage(): string;
 }
+export {};

package/lib/commands/upgrade/2.0.js

@@ -8,6 +8,7 @@ const import_ext_1 = tslib_1.__importDefault(require("../../steps/upgrade/twopoi
 const compat_1 = tslib_1.__importDefault(require("../../steps/upgrade/twopointoh/frontend/export-registry/compat"));
 const usage_of_lazy_modules_1 = tslib_1.__importDefault(require("../../steps/upgrade/twopointoh/frontend/code-splitting/usage-of-lazy-modules"));
 const misc_1 = tslib_1.__importDefault(require("../../steps/upgrade/twopointoh/frontend/misc"));
+const admin_extender_1 = tslib_1.__importDefault(require("../../steps/upgrade/twopointoh/frontend/admin-extender"));
 const format_1 = tslib_1.__importDefault(require("../../steps/upgrade/twopointoh/frontend/format"));
 const chalk_1 = tslib_1.__importDefault(require("chalk"));
 const misc_2 = tslib_1.__importDefault(require("../../steps/upgrade/twopointoh/backend/misc"));
@@ -17,14 +18,90 @@ const json_api_1 = tslib_1.__importDefault(require("../../steps/upgrade/twopoint
 const search_1 = tslib_1.__importDefault(require("../../steps/upgrade/twopointoh/backend/search"));
 const less_1 = tslib_1.__importDefault(require("../../steps/upgrade/twopointoh/less"));
 const phpunit_1 = tslib_1.__importDefault(require("../../steps/upgrade/twopointoh/backend/phpunit"));
+const model_factories_1 = tslib_1.__importDefault(require("../../steps/upgrade/twopointoh/backend/model-factories"));
 const core_1 = require("@oclif/core");
 const email_views_1 = tslib_1.__importDefault(require("../../steps/upgrade/twopointoh/backend/email-views"));
 const intervention_image_1 = tslib_1.__importDefault(require("../../steps/upgrade/twopointoh/backend/intervention-image"));
+const child_process_1 = require("child_process");
+const fs_1 = tslib_1.__importDefault(require("fs"));
+const os_1 = tslib_1.__importDefault(require("os"));
+const path_1 = tslib_1.__importDefault(require("path"));
+const simple_git_1 = tslib_1.__importDefault(require("simple-git"));
 class TwoPointOh extends base_command_1.default {
     constructor() {
         super(...arguments);
         this.requireExistingExtension = true;
         this.skipFinalMessage = true;
+        /**
+         * The steps this run was asked to take, in order.
+         */
+        this.scheduled = [];
+        this.checkout = null;
+    }
+    async run() {
+        try {
+            await super.run();
+        }
+        finally {
+            await this.removeCheckout();
+        }
+    }
+    async additionalPreRunChecks(extRoot) {
+        if (this.flags.check) {
+            this.checkout = await this.createCheckout(extRoot);
+        }
+    }
+    stepsPath(requested) {
+        var _a, _b;
+        return (_b = (_a = this.checkout) === null || _a === void 0 ? void 0 : _a.root) !== null && _b !== void 0 ? _b : requested;
+    }
+    genIO() {
+        var _a;
+        // A check asks nothing: there is nothing to confirm.
+        if ((_a = this.flags) === null || _a === void 0 ? void 0 : _a.check)
+            this.flags['no-interaction'] = true;
+        return super.genIO();
+    }
+    async createCheckout(extRoot) {
+        const root = fs_1.default.realpathSync(extRoot);
+        const git = (0, simple_git_1.default)(root);
+        let repo;
+        try {
+            repo = (await git.revparse(['--show-toplevel'])).trim();
+        }
+        catch (_a) {
+            this.error('--check runs the upgrade on a copy of the extension in a git worktree, so the extension must be in a git repository.', {
+                code: 'FL_ERR',
+            });
+        }
+        const commit = (await git.revparse(['HEAD'])).trim();
+        const dirty = !(await git.status()).isClean();
+        const worktree = fs_1.default.mkdtempSync(path_1.default.join(fs_1.default.realpathSync(os_1.default.tmpdir()), 'flarum-upgrade-check-'));
+        const branch = `flarum-upgrade-check/${path_1.default.basename(worktree)}`;
+        await (0, simple_git_1.default)(repo).raw(['worktree', 'add', '--quiet', '-b', branch, worktree, commit]);
+        return { repo, worktree, branch, root: path_1.default.join(worktree, path_1.default.relative(repo, root)), commit, dirty, cwd: process.cwd() };
+    }
+    /** Remove the worktree and its branch, saying so if it can't. */
+    async removeCheckout() {
+        const checkout = this.checkout;
+        if (!checkout)
+            return;
+        this.checkout = null;
+        // The steps ran from inside the worktree.
+        process.chdir(checkout.cwd);
+        try {
+            await (0, simple_git_1.default)(checkout.repo).raw(['worktree', 'remove', '--force', checkout.worktree]);
+            await (0, simple_git_1.default)(checkout.repo).raw(['branch', '-D', checkout.branch]);
+        }
+        catch (error) {
+            process.stderr.write(`The check could not remove its worktree ${checkout.worktree} and branch ${checkout.branch}: ${error.message}\n` +
+                `Remove them with: git worktree remove --force ${checkout.worktree} && git branch -D ${checkout.branch}\n`);
+        }
+    }
+    /** What a step that committed in the worktree would change, from its commit. */
+    wouldChange(sha) {
+        const show = (...args) => (0, child_process_1.execFileSync)('git', ['show', '--format=', '--no-color', '--no-ext-diff', ...args, sha], { cwd: this.checkout.worktree, encoding: 'utf8' });
+        return { files: show('--name-only').split('\n').filter(Boolean), diff: show() };
     }
     steps(steps, extRoot) {
         // Error.stackTraceLimit = Number.POSITIVE_INFINITY;
@@ -37,6 +114,7 @@ class TwoPointOh extends base_command_1.default {
             import_ext_1.default,
             usage_of_lazy_modules_1.default,
             misc_1.default,
+            admin_extender_1.default,
             // Backend
             misc_2.default,
             filesystem_1.default,
@@ -45,6 +123,7 @@ class TwoPointOh extends base_command_1.default {
             json_api_1.default,
             intervention_image_1.default,
             search_1.default,
+            model_factories_1.default,
             phpunit_1.default,
             // LESS
             less_1.default,
@@ -57,23 +136,44 @@ class TwoPointOh extends base_command_1.default {
             total++;
         });
         collection = collection.map((Step) => {
-            const step = new Step(this, extRoot, stepCount, total, this.flags['force-steps']);
+            var _a, _b;
+            const step = new Step(this, (_b = (_a = this.checkout) === null || _a === void 0 ? void 0 : _a.root) !== null && _b !== void 0 ? _b : extRoot, stepCount, total, this.flags['force-steps'] || this.flags.check);
+            step.checking = Boolean(this.flags.check);
             stepCount++;
             return step;
         });
         if (this.flags.step) {
             const step = Number.parseInt(this.flags.step, 10);
             if (step > 0 && step <= total) {
+                this.scheduled = [collection[step - 1]];
                 return steps.step(collection[step - 1]);
             }
             this.error(`Invalid step number. Please provide a number between 1 and ${total}`);
         }
+        this.scheduled = collection;
         collection.forEach((step) => {
             steps.step(step);
         });
         return steps;
     }
+    jsonReport(succeeded, error, messages) {
+        return Object.assign(Object.assign(Object.assign({}, super.jsonReport(succeeded, error, messages)), (this.checkout && { check: { commit: this.checkout.commit, uncommittedChangesLeftOut: this.checkout.dirty } })), { steps: this.scheduled.map((step) => (Object.assign({ step: step.number, title: step.type }, this.reported(step)))) });
+    }
+    /** A step's outcome, as what it would change when checking. */
+    reported(step) {
+        var _a;
+        const outcome = (_a = step.outcome) !== null && _a !== void 0 ? _a : { status: 'not-run' };
+        if (!this.checkout || outcome.status !== 'committed')
+            return outcome;
+        return Object.assign(Object.assign({ status: 'would-change' }, this.wouldChange(outcome.commit.sha)), { notes: outcome.notes, todos: outcome.todos });
+    }
     welcomeMessage() {
+        if (this.flags.check) {
+            return `
+    Checking what the Flarum 2.0 upgrade would change in your extension. The steps run on its last commit,
+    in a temporary git worktree that is removed afterwards: nothing in your extension changes.
+    `;
+        }
         const beforeProceeding = chalk_1.default.bold.red('Before proceeding:');
         const command = chalk_1.default.bold.bgYellow.black('fl update js-imports');
         const makeSure = chalk_1.default.bold.dim(`- Make sure your extend.php file directly returns an array of extenders.
@@ -90,6 +190,25 @@ class TwoPointOh extends base_command_1.default {
     `;
     }
     goodbyeMessage() {
+        if (this.checkout) {
+            const changing = this.scheduled.filter((step) => { var _a; return ((_a = step.outcome) === null || _a === void 0 ? void 0 : _a.status) === 'committed'; });
+            const lines = changing.map((step) => {
+                const { files } = this.wouldChange(step.outcome.commit.sha);
+                return `    - Step ${step.number}, ${step.type} ${chalk_1.default.dim(files.join(', '))}`;
+            });
+            return [
+                changing.length > 0
+                    ? `    ${changing.length} of the steps would change something in ${this.checkout.commit.slice(0, 7)}:`
+                    : `    None of the steps would change anything in ${this.checkout.commit.slice(0, 7)}.`,
+                ...lines,
+                this.checkout.dirty && '    Changes that were not committed were left out of the check.',
+                '',
+                '    Nothing was changed. Run with --json as well to see each diff, or without --check to make the changes.',
+                '',
+            ]
+                .filter((line) => line !== false)
+                .join('\n');
+        }
         const composer = chalk_1.default.bold.bgYellow('composer update');
         const yarn = chalk_1.default.bold.bgYellow('yarn install');
         return `    Your extension has been successfully upgraded to Flarum 2.0.
@@ -103,11 +222,18 @@ class TwoPointOh extends base_command_1.default {
 }
 exports.default = TwoPointOh;
 TwoPointOh.description = 'Upgrade an extension to Flarum 2.0';
-TwoPointOh.flags = Object.assign(Object.assign({}, base_command_1.default.flags), { step: core_1.Flags.string({
+TwoPointOh.enableJsonFlag = true;
+TwoPointOh.flags = Object.assign(Object.assign({}, base_command_1.default.flags), { json: core_1.Flags.boolean({
+        description: "Report each step's outcome, failures, notes and the @TODOs it left as JSON, for a program driving the upgrade. Implies --no-interaction.",
+        required: false,
+    }), step: core_1.Flags.string({
         description: 'Optionally specify a specific step to run',
         required: false,
     }), 'force-steps': core_1.Flags.boolean({
         description: 'Force run steps even if already ran',
         required: false,
+    }), check: core_1.Flags.boolean({
+        description: 'Report what the upgrade would change, such as on an extension already on Flarum 2.0, without changing it: the steps run on the last commit, in a temporary git worktree that is removed afterwards. Implies --force-steps and --no-interaction.',
+        required: false,
     }) });
 TwoPointOh.args = [...base_command_1.default.args];

package/lib/steps/gen-ext-scaffolder.d.ts

@@ -1,4 +1,9 @@
 import { Scaffolder } from 'boilersmith/scaffolding/scaffolder';
+/**
+ * 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").
+ */
+export declare function licenseTextFor(licenseType: unknown): string;
 export declare const EXTENSION_PARAMS: readonly ["packageName", "packageDescription", "packageNamespace", "authorName", "authorEmail", "extensionName", "licenseType", "mainGitBranch", "jsPackageManager", "licenseText", "extensionId", "year", "backendDirectory", "frontendDirectory"];
 export type ExtensionParams = (typeof EXTENSION_PARAMS)[number];
 export declare const EXTENSION_MODULES: readonly ["core", "icon", "admin", "forum", "js", "jsCommon", "css", "locale", "gitConf", "githubActions", "prettier", "typescript", "bundlewatch", "frontendTesting", "backendTesting", "phpstan", "editorConfig", "styleci"];