Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 | 1x 1x 1x 1x 1x 1x 1x 13x 13x 1x 12x 1x 11x 12x 12x 12x 4x 8x 1x 5x 5x 5x 5x 14x 14x 14x 14x 3x 11x 11x 11x 1x 11x 10x 5x 5x 5x 1x 1x 1x 4x 4x 1x 3x 1x 2x 2x 2x 2x 1x 1x 1x 1x 1x 1x 1x 10x 2x 8x 8x 8x 1x 7x 11x 2x 9x 9x 9x 9x 1x 8x 8x 7x 7x 1x 4x 4x 3x 3x 3x 2x 2x 1x 1x 1x 1x 1x | // Copyright 2026 ForgeKit Contributors
// SPDX-License-Identifier: Apache-2.0
// https://github.com/SubhanshuMG/ForgeKit
import * as fs from 'fs';
import * as path from 'path';
import * as os from 'os';
import { spawnSync } from 'child_process';
import { Command } from 'commander';
/**
* Contract that every ForgeKit plugin must satisfy.
* Plugins are npm packages named `forgekit-plugin-*` that export
* a default object conforming to this interface.
*/
export interface ForgeKitPlugin {
name: string;
version: string;
description?: string;
register(program: Command): void;
}
export interface InstalledPlugin {
name: string;
packageName: string;
version: string;
description: string;
}
const PLUGINS_DIR = path.join(os.homedir(), '.forgekit', 'plugins');
const NODE_MODULES_DIR = path.join(PLUGINS_DIR, 'node_modules');
const PLUGIN_PREFIX = 'forgekit-plugin-';
/**
* Normalizes a user-provided plugin name to a full npm package name.
* Accepts both "foo" and "forgekit-plugin-foo", returns "forgekit-plugin-foo".
*/
function normalizePackageName(name: string): string {
const trimmed = name.trim();
if (!trimmed) {
throw new Error('Plugin name must not be empty.');
}
if (trimmed.startsWith(PLUGIN_PREFIX)) {
return trimmed;
}
return `${PLUGIN_PREFIX}${trimmed}`;
}
/**
* Extracts the short display name from a full package name.
* "forgekit-plugin-docker" -> "docker"
*/
function shortName(packageName: string): string {
if (packageName.startsWith(PLUGIN_PREFIX)) {
return packageName.slice(PLUGIN_PREFIX.length);
}
return packageName;
}
/**
* Validates that a plugin name contains only safe characters.
* Prevents path traversal and command injection via malicious names.
*/
function validatePluginName(name: string): void {
if (!/^[a-z0-9][a-z0-9._-]*$/i.test(name)) {
throw new Error(
`Invalid plugin name "${name}". Names must start with a letter or digit ` +
`and contain only letters, digits, dots, hyphens, and underscores.`
);
}
if (name.includes('..') || name.includes('/') || name.includes('\\')) {
throw new Error(
`Invalid plugin name "${name}". Names must not contain path separators or "..".`
);
}
}
function ensurePluginsDir(): void {
fs.mkdirSync(PLUGINS_DIR, { recursive: true, mode: 0o755 });
// npm install --prefix needs a package.json in the target directory
const pkgJsonPath = path.join(PLUGINS_DIR, 'package.json');
try {
fs.writeFileSync(pkgJsonPath, JSON.stringify({
name: 'forgekit-plugins',
version: '1.0.0',
private: true,
description: 'ForgeKit plugin host directory',
}, null, 2), { encoding: 'utf-8', flag: 'wx' });
} catch {
// File already exists, ignore
}
}
/**
* Reads the package.json of an installed plugin and returns its metadata.
* Returns null if the directory does not exist or the package.json is unreadable.
*/
function readPluginPackageJson(packageName: string): InstalledPlugin | null {
const pkgDir = path.join(NODE_MODULES_DIR, packageName);
const pkgJsonPath = path.join(pkgDir, 'package.json');
try {
if (!fs.existsSync(pkgJsonPath)) {
return null;
}
const raw = fs.readFileSync(pkgJsonPath, 'utf-8');
const pkg = JSON.parse(raw);
return {
name: shortName(packageName),
packageName,
version: typeof pkg.version === 'string' ? pkg.version : '0.0.0',
description: typeof pkg.description === 'string' ? pkg.description : '',
};
} catch {
return null;
}
}
/**
* Install a plugin by name. Runs `npm install` in the plugins directory.
* Returns metadata about the installed plugin.
*/
export async function installPlugin(name: string): Promise<InstalledPlugin> {
const packageName = normalizePackageName(name);
validatePluginName(packageName);
ensurePluginsDir();
const result = spawnSync('npm', ['install', '--save', packageName], {
cwd: PLUGINS_DIR,
encoding: 'utf-8',
timeout: 120_000,
env: { ...process.env, NODE_ENV: '' },
});
if (result.status !== 0) {
const stderr = (result.stderr || '').trim();
const message = stderr || result.error?.message || 'Unknown error';
throw new Error(`Failed to install plugin "${packageName}": ${message}`);
}
const installed = readPluginPackageJson(packageName);
if (!installed) {
throw new Error(
`Plugin "${packageName}" was installed but its package.json could not be read. ` +
`The package may not be a valid ForgeKit plugin.`
);
}
return installed;
}
/**
* Remove an installed plugin. Runs `npm uninstall` in the plugins directory.
*/
export async function removePlugin(name: string): Promise<void> {
const packageName = normalizePackageName(name);
validatePluginName(packageName);
const existing = readPluginPackageJson(packageName);
if (!existing) {
throw new Error(`Plugin "${shortName(packageName)}" is not installed.`);
}
const result = spawnSync('npm', ['uninstall', '--save', packageName], {
cwd: PLUGINS_DIR,
encoding: 'utf-8',
timeout: 60_000,
env: { ...process.env, NODE_ENV: '' },
});
if (result.status !== 0) {
const stderr = (result.stderr || '').trim();
const message = stderr || result.error?.message || 'Unknown error';
throw new Error(`Failed to remove plugin "${packageName}": ${message}`);
}
}
/**
* List all installed plugins by scanning node_modules for forgekit-plugin-* directories.
*/
export function listInstalledPlugins(): InstalledPlugin[] {
if (!fs.existsSync(NODE_MODULES_DIR)) {
return [];
}
const plugins: InstalledPlugin[] = [];
let entries: string[];
try {
entries = fs.readdirSync(NODE_MODULES_DIR);
} catch {
return [];
}
for (const entry of entries) {
if (!entry.startsWith(PLUGIN_PREFIX)) {
continue;
}
// Skip hidden files and non-directories
const entryPath = path.join(NODE_MODULES_DIR, entry);
try {
const stat = fs.statSync(entryPath);
if (!stat.isDirectory()) {
continue;
}
} catch {
continue;
}
const plugin = readPluginPackageJson(entry);
if (plugin) {
plugins.push(plugin);
}
}
return plugins.sort((a, b) => a.name.localeCompare(b.name));
}
/**
* Load all installed plugins and register their commands with the program.
* Each plugin is loaded in isolation -- a failing plugin is logged and skipped
* so it never crashes the entire CLI.
*/
export function loadPlugins(program: Command): void {
const plugins = listInstalledPlugins();
for (const pluginMeta of plugins) {
const modulePath = path.join(NODE_MODULES_DIR, pluginMeta.packageName);
try {
// eslint-disable-next-line @typescript-eslint/no-var-requires
const mod = require(modulePath);
const plugin: ForgeKitPlugin = mod.default || mod;
if (typeof plugin.register !== 'function') {
console.warn(
`Warning: Plugin "${pluginMeta.name}" does not export a register() function. Skipping.`
);
continue;
}
plugin.register(program);
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
console.warn(
`Warning: Failed to load plugin "${pluginMeta.name}": ${message}. Skipping.`
);
}
}
}
|