arcway 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcway",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "A convention-based framework for building modular monoliths with strict domain boundaries.",
   "license": "MIT",
   "type": "module",

package/server/boot/index.js

@@ -28,7 +28,10 @@ async function boot(options) {
   const envFiles = loadEnvFiles(rootDir, mode);
   const config = await makeConfig(rootDir, { overrides: options.configOverrides, mode });
 
-  const plugins = await createPluginManager(config.plugins, { runLifecycle: false });
+  const plugins = await createPluginManager(config.plugins, {
+    runLifecycle: false,
+    bundle: mode === 'development',
+  });
 
   const infrastructure = await createInfrastructure(config, { runMigrations: true });
   const { db, redis, queue, cache, files, mail, events, log } = infrastructure;
@@ -110,6 +113,7 @@ async function boot(options) {
     sessionConfig: config.session,
   });
   await apiRouter.init();
+  if (fileWatcher) plugins.watch(fileWatcher, { apiRouter, jobRunner });
 
   const pagesRouter = new PagesRouter(config, { rootDir, log, mode, fileWatcher, appContext });
   await pagesRouter.init();
@@ -166,6 +170,7 @@ async function boot(options) {
     if (workerPool) await workerPool.shutdown();
     await pagesRouter.close();
     await apiRouter.close();
+    if (fileWatcher) plugins.unwatch(fileWatcher);
     if (viteRouter) await viteRouter.close();
     await webServer.close();
     if (fileWatcher) await fileWatcher.close();

package/server/context.js

@@ -1,4 +1,5 @@
 import * as vault from './lib/vault/index.js';
+import { createJwtCodec } from './lib/vault/jwt.js';
 import { wsBroadcastToPath, wsSendToSocket } from './ws/registry.js';
 
 function trackDb(db) {
@@ -114,9 +115,11 @@ function normalizeMeta(meta) {
 
 function buildVaultToolkit(vaultConfig) {
   if (!vaultConfig?.masterSecret) return vault;
+  const jwtCodec = createJwtCodec(vaultConfig.values?.jwt);
 
   return {
     ...vault,
+    ...jwtCodec,
     deriveKey: (label) => vault.deriveKey(vaultConfig.masterSecret, label),
     deriveKeyPair: (label, opts) => vault.deriveKeyPair(vaultConfig.masterSecret, label, opts),
   };

package/server/jobs/runner.js

@@ -5,8 +5,7 @@ import { toError, calculateBackoff } from './queue.js';
 import JobDispatcher from './drivers/memory-queue.js';
 import { SYSTEM_JOB_DOMAIN, registerSystemJobs } from '../system-jobs/index.js';
 
-async function discoverJobs(jobsDir) {
-  const entries = await discoverModules(jobsDir, { recursive: true, label: 'job file' });
+function buildJobsFromModules(entries) {
   const jobs = [];
   for (const { name, filePath, relativePath, module } of entries) {
     const job = module.default;
@@ -31,6 +30,11 @@ async function discoverJobs(jobsDir) {
   return jobs;
 }
 
+async function discoverJobs(jobsDir) {
+  const entries = await discoverModules(jobsDir, { recursive: true, label: 'job file' });
+  return buildJobsFromModules(entries);
+}
+
 class JobRunner {
   _dispatcher;
   _config;
@@ -42,6 +46,7 @@ class JobRunner {
   _timer = null;
   _started = false;
   _stopped = false;
+  _runGeneration = 0;
   _lastEnqueuedMinute = new Map();
 
   constructor(
@@ -135,10 +140,23 @@ class JobRunner {
     }
   }
 
+  async reload() {
+    const wasStarted = this._started;
+    this.stop();
+    this._jobs = [];
+    this._cronEntries = [];
+    this._continuousJobs = [];
+    this._lastEnqueuedMinute = new Map();
+    this._dispatcher.registered.clear();
+    await this.init();
+    if (wasStarted) this.start();
+  }
+
   start(intervalMs) {
     if (this._started) return;
     this._started = true;
     this._stopped = false;
+    const generation = ++this._runGeneration;
     const pollMs = intervalMs ?? this._config?.pollIntervalMs ?? 60000;
     this._timer = setInterval(() => {
       this.tick().catch((err) => {
@@ -146,7 +164,7 @@ class JobRunner {
       });
     }, pollMs);
     for (const entry of this._continuousJobs) {
-      this._runContinuousLoop(entry);
+      this._runContinuousLoop(entry, generation);
     }
 
     const parts = [];
@@ -158,6 +176,7 @@ class JobRunner {
   stop() {
     this._stopped = true;
     this._started = false;
+    this._runGeneration++;
     if (this._timer) {
       clearInterval(this._timer);
       this._timer = null;
@@ -188,12 +207,12 @@ class JobRunner {
     await this._dispatcher.process();
   }
 
-  async _runContinuousLoop(entry) {
+  async _runContinuousLoop(entry, generation) {
     const backoffMs = this._config?.backoffMs ?? 1000;
     const cooldownMs = entry.cooldownMs ?? this._config?.cooldownMs ?? 1000;
     let consecutiveErrors = 0;
     console.log(`[job-runner] continuous: ${entry.qualifiedName} started`);
-    while (!this._stopped) {
+    while (!this._stopped && generation === this._runGeneration) {
       try {
         const start = Date.now();
         const ctx = buildContext(entry.appContext, { payload: void 0 });
@@ -206,7 +225,7 @@ class JobRunner {
         if (cooldownMs > 0 && elapsed < cooldownMs) {
           const remaining = cooldownMs - elapsed;
           const deadline = Date.now() + remaining;
-          while (!this._stopped && Date.now() < deadline) {
+          while (!this._stopped && generation === this._runGeneration && Date.now() < deadline) {
             await new Promise((r) => setTimeout(r, Math.min(100, deadline - Date.now())));
           }
         }
@@ -219,7 +238,7 @@ class JobRunner {
           error.message,
         );
         const deadline = Date.now() + delay;
-        while (!this._stopped && Date.now() < deadline) {
+        while (!this._stopped && generation === this._runGeneration && Date.now() < deadline) {
           await new Promise((r) => setTimeout(r, Math.min(100, deadline - Date.now())));
         }
       }
@@ -228,4 +247,4 @@ class JobRunner {
   }
 }
 
-export { JobRunner, discoverJobs };
+export { JobRunner, buildJobsFromModules, discoverJobs };

package/server/lib/vault/jwt.js

@@ -1,19 +1,26 @@
-import { SignJWT, jwtVerify, errors } from 'jose';
+import { SignJWT, jwtVerify } from 'jose';
+
 function secretToKey(secret) {
   return new TextEncoder().encode(secret);
 }
+
 function parseExpiration(expiresIn) {
   if (typeof expiresIn === 'number') {
     return `${expiresIn}s`;
   }
   return expiresIn;
 }
-async function jwtEncode(payload, secret, options) {
+
+function requireJwtSecret(secret) {
   if (!secret) {
-    throw new Error('JWT secret is required');
+    throw new Error('JWT key is required');
   }
+  return secret;
+}
+
+async function encodeWithSecret(payload, secret, options) {
   const alg = options?.algorithm ?? 'HS256';
-  const key = secretToKey(secret);
+  const key = secretToKey(requireJwtSecret(secret));
   let builder = new SignJWT(payload).setProtectedHeader({ alg }).setIssuedAt();
   if (options?.expiresIn !== void 0) {
     builder = builder.setExpirationTime(parseExpiration(options.expiresIn));
@@ -26,11 +33,9 @@ async function jwtEncode(payload, secret, options) {
   }
   return builder.sign(key);
 }
-async function jwtDecode(token, secret, options) {
-  if (!secret) {
-    throw new Error('JWT secret is required');
-  }
-  const key = secretToKey(secret);
+
+async function decodeWithSecret(token, secret, options) {
+  const key = secretToKey(requireJwtSecret(secret));
   const algorithms = options?.algorithms ?? ['HS256'];
   try {
     const { payload } = await jwtVerify(token, key, {
@@ -39,17 +44,25 @@ async function jwtDecode(token, secret, options) {
       audience: options?.audience,
     });
     return payload;
-  } catch (err) {
-    if (err instanceof errors.JWTExpired) {
-      throw new Error('JWT token has expired');
-    }
-    if (err instanceof errors.JWSSignatureVerificationFailed) {
-      throw new Error('JWT signature verification failed');
-    }
-    if (err instanceof errors.JWTClaimValidationFailed) {
-      throw new Error(`JWT claim validation failed: ${err.message}`);
-    }
-    throw new Error(`JWT verification failed: ${err.message}`);
+  } catch {
+    throw new Error('JWT verification failed');
   }
 }
-export { jwtDecode, jwtEncode };
+
+function createJwtCodec(secret) {
+  const jwtSecret = requireJwtSecret(secret);
+  return {
+    jwtEncode: (payload, options) => encodeWithSecret(payload, jwtSecret, options),
+    jwtDecode: (token, options) => decodeWithSecret(token, jwtSecret, options),
+  };
+}
+
+async function jwtEncode(_payload, _options) {
+  throw new Error('JWT key is required; use ctx.vault.jwtEncode() with configured vault');
+}
+
+async function jwtDecode(_token, _options) {
+  throw new Error('JWT key is required; use ctx.vault.jwtDecode() with configured vault');
+}
+
+export { createJwtCodec, jwtDecode, jwtEncode };

package/server/lib/vault/secrets.js

@@ -5,7 +5,7 @@ const MASTER_BYTES = 32;
 const VAULT_KEY_BYTES = 32;
 const HKDF_SALT = 'arcway:infra-secrets:v1';
 
-const SECRET_NAMES = Object.freeze(['session', 'plugin-vault', 'mcp-api']);
+const SECRET_NAMES = Object.freeze(['session', 'plugin-vault', 'mcp-api', 'jwt']);
 
 function base64Url(buffer) {
   return Buffer.from(buffer).toString('base64url');
@@ -102,6 +102,7 @@ function deriveInfraSecret(master, name) {
   if (name === 'session') return base64Url(deriveBytes(master, name, 48));
   if (name === 'plugin-vault') return formatVaultKey(deriveBytes(master, name, VAULT_KEY_BYTES));
   if (name === 'mcp-api') return base64Url(deriveBytes(master, name, 48));
+  if (name === 'jwt') return base64Url(deriveBytes(master, name, 48));
   throw new Error(`Unknown Arcway infra secret namespace: ${name}`);
 }
 

package/server/plugins/bundle.js

@@ -0,0 +1,122 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { build } from 'esbuild';
+import { discoverFiles } from '../discovery.js';
+import { loadModule } from '../module-loader.js';
+
+let bundleCounter = 0;
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch (err) {
+    if (err.code === 'ENOENT') return false;
+    throw err;
+  }
+}
+
+function importLine(name, filePath, namespace = true) {
+  const imported = namespace ? `* as ${name}` : name;
+  return `import ${imported} from ${JSON.stringify(filePath)};`;
+}
+
+function moduleEntry(name, entry) {
+  return `{ name: ${JSON.stringify(entry.name)}, filePath: ${JSON.stringify(entry.filePath)}, relativePath: ${JSON.stringify(entry.relativePath)}, module: ${name} }`;
+}
+
+async function loadPluginBundle(packageDir) {
+  const bundleDir = path.join(packageDir, '.arcway', 'plugin-bundles');
+  await fs.mkdir(bundleDir, { recursive: true });
+
+  const pluginJs = path.join(packageDir, 'plugin.js');
+  const exportsJs = path.join(packageDir, 'exports.js');
+  const routesDir = path.join(packageDir, 'routes');
+  const jobsDir = path.join(packageDir, 'jobs');
+  const capabilitiesDir = path.join(packageDir, 'capabilities');
+  const hooksDir = path.join(packageDir, 'hooks');
+
+  const hasPluginJs = await exists(pluginJs);
+  const hasExportsJs = await exists(exportsJs);
+  const routes = await discoverFiles(routesDir, { recursive: true });
+  const jobs = await discoverFiles(jobsDir, { recursive: true });
+  const capabilities = await discoverFiles(capabilitiesDir);
+  const hooks = await discoverFiles(hooksDir);
+
+  const lines = [];
+  if (hasPluginJs) lines.push(importLine('pluginModule', pluginJs));
+  if (hasExportsJs) lines.push(importLine('pluginExports', exportsJs, false));
+
+  for (const [index, entry] of routes.entries()) {
+    lines.push(importLine(`route${index}`, entry.filePath));
+  }
+  for (const [index, entry] of jobs.entries()) {
+    lines.push(importLine(`job${index}`, entry.filePath));
+  }
+  for (const [index, entry] of capabilities.entries()) {
+    lines.push(importLine(`capability${index}`, entry.filePath, false));
+  }
+  for (const [index, entry] of hooks.entries()) {
+    lines.push(importLine(`hook${index}`, entry.filePath, false));
+  }
+
+  lines.push(`export const module = ${hasPluginJs ? 'pluginModule' : '{}'};`);
+  lines.push(
+    `export const exportsModule = ${hasExportsJs ? '{ default: pluginExports }' : 'null'};`,
+  );
+  lines.push(
+    `export const routes = [${routes.map((entry, index) => moduleEntry(`route${index}`, entry)).join(',')}];`,
+  );
+  lines.push(
+    `export const jobs = [${jobs.map((entry, index) => moduleEntry(`job${index}`, entry)).join(',')}];`,
+  );
+  lines.push(
+    `export const capabilities = {${capabilities
+      .map((entry, index) => {
+        const name = path.basename(entry.name, path.extname(entry.name));
+        return `${JSON.stringify(name)}: capability${index}`;
+      })
+      .join(',')}};`,
+  );
+  lines.push(
+    `export const hooks = {${hooks
+      .map((entry, index) => {
+        const name = path.basename(entry.name, path.extname(entry.name));
+        return `${JSON.stringify(name)}: hook${index}`;
+      })
+      .join(',')}};`,
+  );
+
+  const counter = ++bundleCounter;
+  const entryPath = path.join(bundleDir, `entry-${counter}.mjs`);
+  const outFile = path.join(bundleDir, `bundle-${counter}.mjs`);
+  await fs.writeFile(entryPath, lines.join('\n'));
+
+  await build({
+    entryPoints: [entryPath],
+    outfile: outFile,
+    bundle: true,
+    format: 'esm',
+    platform: 'node',
+    target: 'node20',
+    logLevel: 'silent',
+  });
+
+  const bundled = await loadModule(outFile);
+  return {
+    module: bundled.module ?? {},
+    exportsModule: bundled.exportsModule ?? null,
+    routes: bundled.routes ?? [],
+    jobs: bundled.jobs ?? [],
+    capabilities: bundled.capabilities ?? {},
+    hooks: bundled.hooks ?? {},
+    artifact: outFile,
+  };
+}
+
+function fileUrl(filePath) {
+  return pathToFileURL(filePath).href;
+}
+
+export { fileUrl, loadPluginBundle };

package/server/plugins/discovery.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { discoverModules, discoverPackageDirectories } from '../discovery.js';
 import { loadModule } from '../module-loader.js';
 import { validateManifest } from './manifest.js';
+import { loadPluginBundle } from './bundle.js';
 
 async function exists(filePath) {
   try {
@@ -60,7 +61,7 @@ async function loadConventionModules(dir, label) {
   return map;
 }
 
-async function loadPluginPackage(packageDir) {
+async function loadPluginPackage(packageDir, { bundle = false } = {}) {
   const packageJsonPath = path.join(packageDir, 'package.json');
   if (!(await exists(packageJsonPath))) {
     throw new Error(`Plugin package at ${packageDir} must include package.json`);
@@ -72,11 +73,17 @@ async function loadPluginPackage(packageDir) {
   const exportsJs = path.join(packageDir, 'exports.js');
   let manifestPath;
   let module = {};
+  let bundled = null;
   let rawManifest;
 
   if (await exists(pluginJs)) {
     manifestPath = pluginJs;
-    module = await loadModule(pluginJs, import.meta.url);
+    if (bundle) {
+      bundled = await loadPluginBundle(packageDir);
+      module = bundled.module;
+    } else {
+      module = await loadModule(pluginJs, import.meta.url);
+    }
     rawManifest = getManifest(module, pluginJs);
   } else if (await exists(pluginJson)) {
     manifestPath = pluginJson;
@@ -106,9 +113,12 @@ async function loadPluginPackage(packageDir) {
 
   const routesDir = path.join(packageDir, 'routes');
   const jobsDir = path.join(packageDir, 'jobs');
-  const exportsModule = (await exists(exportsJs))
-    ? await loadModule(exportsJs, import.meta.url)
-    : null;
+  if (bundle && !bundled) bundled = await loadPluginBundle(packageDir);
+  const exportsModule = bundled
+    ? bundled.exportsModule
+    : (await exists(exportsJs))
+      ? await loadModule(exportsJs, import.meta.url)
+      : null;
 
   return {
     id: manifest.id,
@@ -116,16 +126,23 @@ async function loadPluginPackage(packageDir) {
     packageJson,
     manifest,
     module,
+    bundle: bundled ? { artifact: bundled.artifact } : null,
     manifestPath,
     exports: exportsModule ? getExports(exportsModule, exportsJs) : {},
     routesDir: (await exists(routesDir)) ? routesDir : null,
     jobsDir: (await exists(jobsDir)) ? jobsDir : null,
-    capabilities: await loadConventionModules(path.join(packageDir, 'capabilities'), 'capability'),
-    hooks: await loadConventionModules(path.join(packageDir, 'hooks'), 'lifecycle hook'),
+    bundledRoutes: bundled?.routes ?? null,
+    bundledJobs: bundled?.jobs ?? null,
+    capabilities:
+      bundled?.capabilities ??
+      (await loadConventionModules(path.join(packageDir, 'capabilities'), 'capability')),
+    hooks:
+      bundled?.hooks ??
+      (await loadConventionModules(path.join(packageDir, 'hooks'), 'lifecycle hook')),
   };
 }
 
-async function discoverPlugins(dirs) {
+async function discoverPlugins(dirs, options = {}) {
   const plugins = [];
   const seen = new Map();
 
@@ -135,7 +152,7 @@ async function discoverPlugins(dirs) {
       label: 'plugin',
     });
     for (const entry of packages) {
-      const plugin = await loadPluginPackage(entry.dir);
+      const plugin = await loadPluginPackage(entry.dir, options);
       if (!plugin) continue;
       if (seen.has(plugin.id)) {
         throw new Error(

package/server/plugins/graph.js

@@ -18,29 +18,43 @@ function buildProviderMap(plugins) {
 function resolvePluginGraph(plugins, enabledIds) {
   const allProviders = buildProviderMap(plugins);
   const byId = new Map(plugins.map((plugin) => [plugin.id, plugin]));
-  const enabled = new Set(enabledIds);
+  const enabled = new Set([...enabledIds].map((id) => String(id)));
   const missing = [];
   const edges = new Map();
 
   for (const plugin of plugins) {
-    edges.set(plugin.id, new Set());
-    if (!enabled.has(plugin.id)) continue;
+    const pluginId = String(plugin.id);
+    edges.set(pluginId, new Set());
+  }
+
+  for (const plugin of plugins) {
+    const pluginId = String(plugin.id);
+    if (!enabled.has(pluginId)) continue;
     for (const capability of requiredCapabilities(plugin.manifest.requires)) {
       const provider = allProviders.get(capability);
       if (!provider) {
-        missing.push({ pluginId: plugin.id, capability, reason: 'missing provider' });
+        missing.push({ pluginId, capability, reason: 'missing provider' });
         continue;
       }
-      if (!enabled.has(provider.id)) {
+      const providerId = String(provider.id);
+      if (!enabled.has(providerId)) {
         missing.push({
-          pluginId: plugin.id,
+          pluginId,
           capability,
-          providerId: provider.id,
+          providerId,
           reason: 'provider disabled',
         });
         continue;
       }
-      if (provider.id !== plugin.id) edges.get(provider.id).add(plugin.id);
+      if (providerId !== pluginId) {
+        const providerEdges = edges.get(providerId);
+        if (!providerEdges) {
+          throw new Error(
+            `Plugin ${pluginId} requires capability ${capability} from unknown provider ${providerId}`,
+          );
+        }
+        providerEdges.add(pluginId);
+      }
     }
   }
 

package/server/plugins/manager.js

@@ -1,5 +1,6 @@
-import { discoverRoutes } from '../router/routes.js';
-import { discoverJobs } from '../jobs/runner.js';
+import path from 'node:path';
+import { buildRoutesFromModules, discoverRoutes } from '../router/routes.js';
+import { buildJobsFromModules, discoverJobs } from '../jobs/runner.js';
 import { CapabilityRegistry } from './capabilities.js';
 import { discoverPlugins } from './discovery.js';
 import { buildProviderMap, cascadeDisabled, resolvePluginGraph } from './graph.js';
@@ -26,6 +27,29 @@ function capabilityFactory(plugin, capability) {
   );
 }
 
+function collectDependentIds(plugins, ids) {
+  const affected = new Set(ids);
+  const providers = buildProviderMap(plugins);
+  let changed = true;
+
+  while (changed) {
+    changed = false;
+    for (const plugin of plugins) {
+      if (affected.has(plugin.id)) continue;
+      for (const capability of requiredCapabilities(plugin.manifest.requires)) {
+        const provider = providers.get(capability);
+        if (provider && affected.has(provider.id)) {
+          affected.add(plugin.id);
+          changed = true;
+          break;
+        }
+      }
+    }
+  }
+
+  return affected;
+}
+
 function bindPluginExports(plugin, ctx) {
   return new Proxy(
     {},
@@ -56,10 +80,11 @@ function bindPluginExports(plugin, ctx) {
 }
 
 class PluginManager {
-  constructor(config, { log, runLifecycle = true } = {}) {
+  constructor(config, { log, runLifecycle = true, bundle = false } = {}) {
     this.config = config ?? { enabled: false, dirs: [] };
     this.log = log;
     this.runLifecycle = runLifecycle;
+    this.bundle = bundle;
     this.plugins = [];
     this.enabled = new Set();
     this.status = new Map();
@@ -70,7 +95,7 @@ class PluginManager {
   async init() {
     if (this.config.enabled !== true) return this;
 
-    this.plugins = await discoverPlugins(this.config.dirs);
+    this.plugins = await discoverPlugins(this.config.dirs, { bundle: this.bundle });
     const enablements = configuredEnablements(this.config);
     this.enabled = new Set(
       this.plugins
@@ -144,14 +169,18 @@ class PluginManager {
   async discoverRoutes() {
     const routes = [];
     for (const plugin of this.enabledPlugins) {
-      if (!plugin.routesDir) continue;
-      const discovered = await discoverRoutes(plugin.routesDir, {
+      const routeOptions = {
         prefix: `/_plugins/${plugin.id}`,
         plugin: {
           id: plugin.id,
           requires: plugin.manifest.requires,
         },
-      });
+      };
+      const discovered = plugin.bundledRoutes
+        ? buildRoutesFromModules(plugin.bundledRoutes, routeOptions)
+        : plugin.routesDir
+          ? await discoverRoutes(plugin.routesDir, routeOptions)
+          : [];
       routes.push(...discovered);
     }
     return routes;
@@ -160,8 +189,11 @@ class PluginManager {
   async discoverJobs() {
     const jobs = [];
     for (const plugin of this.enabledPlugins) {
-      if (!plugin.jobsDir) continue;
-      const discovered = await discoverJobs(plugin.jobsDir);
+      const discovered = plugin.bundledJobs
+        ? buildJobsFromModules(plugin.bundledJobs)
+        : plugin.jobsDir
+          ? await discoverJobs(plugin.jobsDir)
+          : [];
       for (const job of discovered) {
         const definition = {
           ...job.definition,
@@ -177,6 +209,115 @@ class PluginManager {
     return jobs;
   }
 
+  async reload(ids) {
+    if (this.config.enabled !== true) return { reloaded: [] };
+
+    const requested = ids ? new Set(Array.isArray(ids) ? ids : [ids]) : null;
+    const oldPlugins = this.plugins;
+    const oldEnabledIds = new Set(
+      oldPlugins
+        .filter((plugin) => this.status.get(plugin.id) === 'enabled')
+        .map((plugin) => plugin.id),
+    );
+    let affected = requested ? collectDependentIds(oldPlugins, requested) : new Set();
+
+    const discovered = await discoverPlugins(this.config.dirs, { bundle: this.bundle });
+    const discoveredIds = new Set(discovered.map((plugin) => plugin.id));
+    const enablements = configuredEnablements(this.config);
+    const nextEnabled = new Set();
+    for (const plugin of discovered) {
+      if (
+        this.enabled.has(plugin.id) ||
+        (!oldPlugins.some((old) => old.id === plugin.id) &&
+          pluginEnabledByDefault(plugin, enablements))
+      ) {
+        nextEnabled.add(plugin.id);
+      }
+    }
+
+    if (!requested) {
+      affected = new Set([...oldPlugins.map((plugin) => plugin.id), ...discoveredIds]);
+    } else {
+      for (const id of requested) {
+        if (!discoveredIds.has(id) && !oldPlugins.some((plugin) => plugin.id === id)) {
+          affected = new Set([...oldPlugins.map((plugin) => plugin.id), ...discoveredIds]);
+          break;
+        }
+      }
+      affected = collectDependentIds(discovered, affected);
+    }
+
+    const oldAffectedEnabled = [...this.loadOrder]
+      .filter((plugin) => affected.has(plugin.id) && oldEnabledIds.has(plugin.id))
+      .reverse();
+    for (const plugin of oldAffectedEnabled) {
+      if (this.runLifecycle) await this.#runLifecycle(plugin, 'onDisable');
+    }
+
+    this.plugins = discovered;
+    this.enabled = nextEnabled;
+    this.#rebuildGraph();
+
+    for (const plugin of this.loadOrder) {
+      if (!affected.has(plugin.id)) continue;
+      if (this.runLifecycle) {
+        await this.#runLifecycle(plugin, 'onLoad');
+        await this.#runLifecycle(plugin, 'onEnable');
+      }
+      this.log?.info?.(`Plugin reloaded: ${plugin.id}`);
+    }
+
+    return {
+      reloaded: [...affected].filter((id) => discoveredIds.has(id)),
+      removed: [...affected].filter((id) => !discoveredIds.has(id)),
+    };
+  }
+
+  pluginIdsForChangedFiles(events) {
+    const ids = new Set();
+    for (const event of events) {
+      const filePath = event.path;
+      const existing = this.plugins.find(
+        (plugin) => filePath === plugin.dir || filePath.startsWith(plugin.dir + path.sep),
+      );
+      if (existing) {
+        ids.add(existing.id);
+        continue;
+      }
+
+      const rootDir = (this.config.dirs ?? []).find((dir) => {
+        const relative = path.relative(dir, filePath);
+        return relative && !relative.startsWith('..') && !path.isAbsolute(relative);
+      });
+      if (!rootDir) continue;
+      const [packageDirName] = path.relative(rootDir, filePath).split(path.sep);
+      if (!packageDirName) continue;
+      if (!this.plugins.some((plugin) => plugin.id === packageDirName)) return null;
+      ids.add(packageDirName);
+    }
+    return ids;
+  }
+
+  watch(fileWatcher, { apiRouter, jobRunner } = {}) {
+    if (this.config.enabled !== true || !fileWatcher) return;
+    fileWatcher.subscribe('plugins', {
+      dirs: this.config.dirs,
+      extensions: ['.js', '.json'],
+      debounceMs: 200,
+      onChange: async (events) => {
+        const changedIds = this.pluginIdsForChangedFiles(events);
+        await this.reload(changedIds);
+        await apiRouter?.reload?.();
+        await jobRunner?.reload?.();
+      },
+    });
+    this.log?.info?.('Plugins: watching for changes');
+  }
+
+  unwatch(fileWatcher) {
+    fileWatcher?.unsubscribe?.('plugins');
+  }
+
   #rebuildGraph() {
     const providers = buildProviderMap(this.plugins);
     for (const plugin of this.plugins) {

package/server/router/api-router.js

@@ -347,6 +347,10 @@ class ApiRouter {
     }
   }
 
+  async reload() {
+    return this._reload();
+  }
+
   async close() {
     if (this._mode === 'development' && this._fileWatcher) {
       this._fileWatcher.unsubscribe('routes');

package/server/router/routes.js

@@ -46,8 +46,7 @@ function prefixRoutePattern(pattern, prefix) {
   if (pattern === '/') return normalized;
   return normalized + pattern;
 }
-async function discoverRoutes(apiDir, { prefix = '', plugin } = {}) {
-  const entries = await discoverModules(apiDir, { recursive: true, label: 'route file' });
+function buildRoutesFromModules(entries, { prefix = '', plugin } = {}) {
   const routes = [];
   for (const { filePath, relativePath, module } of entries) {
     const urlPattern = prefixRoutePattern(filePathToPattern(relativePath), prefix);
@@ -84,6 +83,11 @@ async function discoverRoutes(apiDir, { prefix = '', plugin } = {}) {
   sortBySpecificity(routes);
   return routes;
 }
+
+async function discoverRoutes(apiDir, { prefix = '', plugin } = {}) {
+  const entries = await discoverModules(apiDir, { recursive: true, label: 'route file' });
+  return buildRoutesFromModules(entries, { prefix, plugin });
+}
 function matchRoute(routes, method, pathname) {
   const upperMethod = method.toUpperCase();
   const methodRoutes = routes.filter((r) => r.method === upperMethod);
@@ -106,6 +110,7 @@ function matchRoutesByPath(routes, pathname) {
 }
 export {
   compilePattern,
+  buildRoutesFromModules,
   discoverRoutes,
   filePathToPattern,
   matchPattern,