Merge pull request #1018 from bbassie/feature/plugin-install

Add plugin install command to controller, host and ctl
This commit is contained in:
Cooldude2606 authored and GitHub committed 2026-09-12 23:35:26 +01:00
commit 8be251447a
6 files changed
+294 -24

No files matched your search

+16 -5
View File
@@ -25,17 +25,28 @@ Configure plugins available to be loaded by the controller.
The available plugins will be loaded unless they have been disabled in the configuration, see the config command for disabling plugins.
#### `plugin install <package>`
Install a plugin from npm and add it to the plugin list.
The package is passed to `npm install --save` so anything npm accepts works, including a version like `@clusterio/plugin-subspace_storage@2.0.0`.
This command refuses to run outside the directory Clusterio was installed in, as the plugin has to end up in that directory's node_modules to be found.
For example, installing the Subspace Storage plugin:
npx clusteriocontroller plugin install @clusterio/plugin-subspace_storage
Since the `plugin-list.json` is shared between controller, host and ctl you usually only need to do this once per machine.
#### `plugin add <path>`
Add plugin either by require path or relative/absolute path to the plugin directory.
A relative path must start with ./ or ../ (or .\ and ..\ on Windows) otherwise it will be assumed to be a require path for an installed package in node_modules.
This is mainly useful for plugins under development, packages published on npm are better installed with `plugin install`.
For example, installing the Subspace Storage plugin:
For example, adding a plugin checked out in the external_plugins directory:
npm install @clusterio/plugin-subspace_storage
npx clusteriocontroller plugin add @clusterio/plugin-subspace_storage
Since the `plugin-list.json` is shared between controller, host and ctl you usually only need to do this once per machine.
npx clusteriocontroller plugin add ./external_plugins/my_plugin
#### `plugin remove <name>`
+16 -5
View File
@@ -27,17 +27,28 @@ Configure plugins available to be loaded by ctl.
The available plugins will be automatically loaded and the commands they provide will be added to the ctl utility.
#### `plugin install <package>`
Install a plugin from npm and add it to the plugin list.
The package is passed to `npm install --save` so anything npm accepts works, including a version like `@clusterio/plugin-subspace_storage@2.0.0`.
This command refuses to run outside the directory Clusterio was installed in, as the plugin has to end up in that directory's node_modules to be found.
For example, installing the Subspace Storage plugin:
npx clusterioctl plugin install @clusterio/plugin-subspace_storage
Since the `plugin-list.json` is shared between controller, host and ctl you usually only need to do this once per machine.
#### `plugin add <path>`
Add plugin either by require path or relative/absolute path to the plugin directory.
A relative path must start with ./ or ../ (or .\ and ..\ on Windows) otherwise it will be assumed to be a require path for an installed package in node_modules.
This is mainly useful for plugins under development, packages published on npm are better installed with `plugin install`.
For example, installing the Subspace Storage plugin:
For example, adding a plugin checked out in the external_plugins directory:
npm install @clusterio/plugin-subspace_storage
npx clusterioctl plugin add @clusterio/plugin-subspace_storage
Since the `plugin-list.json` is shared between controller, host and ctl you usually only need to do this once per machine.
npx clusterioctl plugin add ./external_plugins/my_plugin
#### `plugin remove <name>`
+16 -5
View File
@@ -26,17 +26,28 @@ Configure plugins available to be loaded by the host.
The available plugins will be loaded unless they have been disabled in the configuration, see the config command for disabling plugins.
#### `plugin install <package>`
Install a plugin from npm and add it to the plugin list.
The package is passed to `npm install --save` so anything npm accepts works, including a version like `@clusterio/plugin-subspace_storage@2.0.0`.
This command refuses to run outside the directory Clusterio was installed in, as the plugin has to end up in that directory's node_modules to be found.
For example, installing the Subspace Storage plugin:
npx clusteriohost plugin install @clusterio/plugin-subspace_storage
Since the `plugin-list.json` is shared between controller, host and ctl you usually only need to do this once per machine.
#### `plugin add <path>`
Add plugin either by require path or relative/absolute path to the plugin directory.
A relative path must start with ./ or ../ (or .\ and ..\ on Windows) otherwise it will be assumed to be a require path for an installed package in node_modules.
This is mainly useful for plugins under development, packages published on npm are better installed with `plugin install`.
For example, installing the Subspace Storage plugin:
For example, adding a plugin checked out in the external_plugins directory:
npm install @clusterio/plugin-subspace_storage
npx clusteriohost plugin add @clusterio/plugin-subspace_storage
Since the `plugin-list.json` is shared between controller, host and ctl you usually only need to do this once per machine.
npx clusteriohost plugin add ./external_plugins/my_plugin
#### `plugin remove <name>`
+113 -1
View File
@@ -2,8 +2,11 @@
* Implementation of commands shared between controller/host/ctl.
* @module lib/shared_commands
*/
import fs from "fs/promises";
import path from "path";
import { spawn } from "child_process";
import { loadPluginList } from "./load_plugin_list.js";
import * as libConfig from "./config/index.js";
import * as libFileOps from "./file_ops.js";
import { logger } from "./logging.js";
@@ -27,6 +30,7 @@ function print(...content: any[]) {
*/
export function pluginCommand(yargs: any) {
yargs
.command("install <package>", "Install plugin from npm and add it")
.command("add <path>", "Add plugin by require path")
.command("remove <name>", "Remove plugin by name")
.command("list", "List all plugins and their path")
@@ -36,6 +40,67 @@ export function pluginCommand(yargs: any) {
;
}
const corePackages = ["@clusterio/controller", "@clusterio/host", "@clusterio/ctl"];
/**
* Check if the current directory is a Clusterio installation
*
* A directory counts as an installation if it has a package.json created
* by the installer or one that depends on a Clusterio package.
*/
export async function isClusterioInstall(dir = process.cwd()) {
let packageJson: { name?: string, dependencies?: Record<string, string> };
try {
packageJson = JSON.parse(await fs.readFile(path.join(dir, "package.json"), "utf8"));
} catch (err: any) {
if (err.code === "ENOENT") {
return false;
}
throw err;
}
if (packageJson.name === "clusterio-install") {
return true;
}
return corePackages.some(name => packageJson.dependencies?.[name] !== undefined);
}
async function readDependencies(): Promise<Record<string, string>> {
const packageJson = JSON.parse(await fs.readFile("package.json", "utf8"));
return packageJson.dependencies ?? {};
}
async function packageNameFromSpec(packageSpec: string) {
try {
const packageJson = JSON.parse(await fs.readFile(path.join(packageSpec, "package.json"), "utf8"));
if (typeof packageJson.name === "string") {
return packageJson.name;
}
} catch (err: any) {
if (!["ENOENT", "ENOTDIR"].includes(err.code)) {
throw err;
}
}
return packageSpec.replace(/(?!^)@.*$/, "");
}
function npmInstall(packageSpec: string) {
const npm = process.platform === "win32" ? "npm.cmd" : "npm";
return new Promise<void>((resolve, reject) => {
const child = spawn(npm, ["install", "--save", "--no-audit", "--no-fund", packageSpec], {
stdio: "inherit",
shell: process.platform === "win32",
});
child.on("error", reject);
child.on("exit", code => {
if (code === 0) {
resolve();
} else {
reject(new Error(`npm install exited with code ${code}`));
}
});
});
}
/**
* Handle yargs plugin command
*
@@ -51,11 +116,58 @@ export async function handlePluginCommand(
pluginListPath: string
) {
let command = (args._ as string[])[1];
const wrongDirHint = `${process.cwd()} is not a Clusterio installation, run this command from the directory ` +
"Clusterio was installed in";
if (command === "add") {
if (command === "install") {
if (!await isClusterioInstall()) {
logger.error(wrongDirHint);
process.exitCode = 1;
return;
}
const packageSpec = args.package as string;
const depsBefore = await readDependencies();
try {
await npmInstall(packageSpec);
} catch (err: any) {
logger.error(`Failed to install ${packageSpec}: ${err.message}`);
process.exitCode = 1;
return;
}
const depsAfter = await readDependencies();
const newPluginList = await loadPluginList(pluginListPath);
const added = [...newPluginList.keys()].filter(name => !pluginList.has(name));
for (const name of added) {
pluginList.set(name, newPluginList.get(name)!);
print(`Installed ${name}`);
}
if (added.length) {
return;
}
// Nothing new, either the plugin was already in the list or the package is not a plugin.
let packageNames = Object.keys(depsAfter).filter(name => depsAfter[name] !== depsBefore[name]);
if (!packageNames.length) {
packageNames = [await packageNameFromSpec(packageSpec)];
}
const existing = [...pluginList].filter(([, requirePath]) => packageNames.includes(requirePath));
if (existing.length) {
for (const [name] of existing) {
print(`${name} is already installed`);
}
} else {
logger.error(`${packageSpec} was installed but did not provide any plugins`);
process.exitCode = 1;
}
} else if (command === "add") {
let pluginPath = args.path as string;
if (/^\.\.?[\/\\]/.test(pluginPath)) {
pluginPath = path.resolve(pluginPath);
} else if (!path.isAbsolute(pluginPath) && !await isClusterioInstall()) {
logger.warn(wrongDirHint);
}
let pluginInfo: { name: string };