@flarum/cli 3.0.11 → 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.11 linux-x64 node-v18.19.1
+@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

@@ -7,14 +7,14 @@
   "dependencies": {
   },
   "devDependencies": {
-    "@flarum/jest-config": "^1.0.1",
+    "@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/skeleton/extension/phpstan.neon

@@ -8,5 +8,4 @@ parameters:
     - src
   excludePaths:
     - *.blade.php
-  checkMissingIterableValueType: false
   databaseMigrationsPath: ['migrations']

package/boilerplate/skeleton/extension/tests/phpunit.integration.xml

@@ -6,6 +6,7 @@
     cacheDirectory=".phpunit.cache"
     backupStaticProperties="false"
     colors="true"
+    displayDetailsOnTestsThatTriggerWarnings="true"
     processIsolation="true"
     stopOnFailure="false"
 >

package/boilerplate/skeleton/extension/tests/phpunit.unit.xml

@@ -1,11 +1,12 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <phpunit
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd"
+    xsi:noNamespaceSchemaLocation="../vendor/phpunit/phpunit/phpunit.xsd"
     backupGlobals="false"
     cacheDirectory=".phpunit.cache"
     backupStaticProperties="false"
     colors="true"
+    displayDetailsOnTestsThatTriggerWarnings="true"
     processIsolation="false"
     stopOnFailure="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/monorepo/split.js

@@ -10,7 +10,7 @@ class Split extends base_command_1.default {
         this.requireExistingExtension = false;
     }
     steps(stepManager) {
-        return stepManager.step(new split_1.MonorepoSplit(this.flags.force));
+        return stepManager.step(new split_1.MonorepoSplit(this.flags.force, this.flags['no-interaction']));
     }
 }
 exports.default = Split;

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 {};