arcway 0.1.27 → 0.1.28

package/server/plugins/manifest.js

@@ -0,0 +1,94 @@
+const ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+const KINDS = new Set(['core', 'feature']);
+const SCOPES = new Set(['global', 'workspace']);
+
+function assertPlainObject(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+}
+
+function normalizeStringArray(value, label) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || item === '')) {
+    throw new Error(`${label} must be an array of non-empty strings`);
+  }
+  return [...value];
+}
+
+function normalizeRequires(value) {
+  if (value === undefined) return {};
+  assertPlainObject(value, 'plugin requires');
+  return { ...value };
+}
+
+function normalizeContributes(value) {
+  if (value === undefined) return {};
+  assertPlainObject(value, 'plugin contributes');
+  return {
+    ...value,
+    tools: value.tools ?? [],
+    routes: value.routes ?? [],
+    jobs: value.jobs ?? [],
+    migrations: value.migrations,
+    ui: value.ui,
+  };
+}
+
+function normalizeLifecycle(value) {
+  if (value === undefined) return {};
+  assertPlainObject(value, 'plugin lifecycle');
+  for (const name of ['onLoad', 'onEnable', 'onDisable']) {
+    if (
+      value[name] !== undefined &&
+      typeof value[name] !== 'function' &&
+      typeof value[name] !== 'string'
+    ) {
+      throw new Error(`plugin lifecycle.${name} must be a function or module export name`);
+    }
+  }
+  return { ...value };
+}
+
+function validateManifest(rawManifest, { packageName } = {}) {
+  assertPlainObject(rawManifest, 'plugin manifest');
+
+  const manifest = {
+    id: rawManifest.id ?? packageName,
+    name: rawManifest.name ?? rawManifest.id ?? packageName,
+    version: rawManifest.version,
+    kind: rawManifest.kind ?? 'feature',
+    scope: rawManifest.scope ?? 'workspace',
+    defaultEnabled: rawManifest.defaultEnabled === true,
+    provides: normalizeStringArray(rawManifest.provides, 'plugin provides'),
+    requires: normalizeRequires(rawManifest.requires),
+    contributes: normalizeContributes(rawManifest.contributes),
+    lifecycle: normalizeLifecycle(rawManifest.lifecycle),
+  };
+
+  if (typeof manifest.id !== 'string' || !ID_PATTERN.test(manifest.id)) {
+    throw new Error('plugin id must be lowercase kebab-case');
+  }
+  if (typeof manifest.name !== 'string' || manifest.name === '') {
+    throw new Error(`plugin ${manifest.id} name must be a non-empty string`);
+  }
+  if (typeof manifest.version !== 'string' || manifest.version === '') {
+    throw new Error(`plugin ${manifest.id} version must be a non-empty string`);
+  }
+  if (!KINDS.has(manifest.kind)) {
+    throw new Error(`plugin ${manifest.id} kind must be core or feature`);
+  }
+  if (!SCOPES.has(manifest.scope)) {
+    throw new Error(`plugin ${manifest.id} scope must be global or workspace`);
+  }
+
+  return manifest;
+}
+
+function requiredCapabilities(requires) {
+  return Object.entries(requires ?? {})
+    .filter(([, requirement]) => requirement !== false && requirement !== null)
+    .map(([capability]) => capability);
+}
+
+export { requiredCapabilities, validateManifest };

package/server/router/api-router.js

@@ -39,6 +39,7 @@ class ApiRouter {
   _appContext;
   _sessionConfig;
   _redis;
+  _pluginManager;
   _routes = [];
   _middleware = [];
   _prefix = '';
@@ -53,6 +54,7 @@ class ApiRouter {
     this._appContext = appContext ?? null;
     this._sessionConfig = sessionConfig ?? null;
     this._redis = appContext?.redis ?? null;
+    this._pluginManager = appContext?.plugins ?? null;
   }
 
   get routes() {
@@ -101,6 +103,7 @@ class ApiRouter {
     const chainedHandler = buildMiddlewareChain(middlewareFns, route.config.handler);
     const ctx = this._buildCtx(reqInfo);
     try {
+      if (route.plugin) this._pluginManager?.injectCapabilities(ctx, route.plugin.requires);
       return await chainedHandler(ctx);
     } catch (err) {
       this._log.error(`Handler error in ${route.method} ${route.pattern}`, {
@@ -133,7 +136,10 @@ class ApiRouter {
     );
   }
 
-  _emitCanonicalLog(ctx, { method, path, route, status, startTime, middlewareNames, error, session }) {
+  _emitCanonicalLog(
+    ctx,
+    { method, path, route, status, startTime, middlewareNames, error, session },
+  ) {
     const durationMs = Date.now() - startTime;
     const dbStats = ctx._dbStats ?? { queries: 0, durationMs: 0 };
     const extra = ctx.log.getCanonicalContext?.() ?? {};
@@ -204,17 +210,22 @@ class ApiRouter {
       });
       if (!rl.allowed) {
         const retryAfter = Math.max(1, rl.resetAt - Math.ceil(Date.now() / 1000));
-        sendJson(res, 429, {
-          error: {
-            code: ErrorCodes.RATE_LIMITED,
-            message: `Rate limit exceeded. Try again in ${retryAfter} seconds.`,
+        sendJson(
+          res,
+          429,
+          {
+            error: {
+              code: ErrorCodes.RATE_LIMITED,
+              message: `Rate limit exceeded. Try again in ${retryAfter} seconds.`,
+            },
+          },
+          {
+            'X-RateLimit-Limit': String(max),
+            'X-RateLimit-Remaining': '0',
+            'X-RateLimit-Reset': String(rl.resetAt),
+            'Retry-After': String(retryAfter),
           },
-        }, {
-          'X-RateLimit-Limit': String(max),
-          'X-RateLimit-Remaining': '0',
-          'X-RateLimit-Reset': String(rl.resetAt),
-          'Retry-After': String(retryAfter),
-        });
+        );
         return true;
       }
       res.setHeader('X-RateLimit-Limit', String(max));
@@ -254,6 +265,7 @@ class ApiRouter {
 
     let response;
     try {
+      if (route.plugin) this._pluginManager?.injectCapabilities(ctx, route.plugin.requires);
       response = await chainedHandler(ctx);
     } catch (err) {
       const errorMsg = toErrorMessage(err);
@@ -265,8 +277,14 @@ class ApiRouter {
             : String(err)
           : 'An internal error occurred';
       this._emitCanonicalLog(ctx, {
-        method, path: pathname, route: route.pattern, status: 500,
-        startTime, middlewareNames, error: errorMsg, session: reqInfo.session,
+        method,
+        path: pathname,
+        route: route.pattern,
+        status: 500,
+        startTime,
+        middlewareNames,
+        error: errorMsg,
+        session: reqInfo.session,
       });
       sendJson(res, 500, {
         error: { code: ErrorCodes.HANDLER_ERROR, message: errorMessage },
@@ -294,8 +312,13 @@ class ApiRouter {
     const statusCode = response.status ?? (response.error ? 400 : 200);
     await serializeResponse(res, response, responseHeaders, statusCode);
     this._emitCanonicalLog(ctx, {
-      method, path: pathname, route: route.pattern, status: statusCode,
-      startTime, middlewareNames, session: response.session !== void 0 ? response.session : reqInfo.session,
+      method,
+      path: pathname,
+      route: route.pattern,
+      status: statusCode,
+      startTime,
+      middlewareNames,
+      session: response.session !== void 0 ? response.session : reqInfo.session,
     });
 
     return true;
@@ -331,10 +354,12 @@ class ApiRouter {
   }
 
   async _discover() {
-    const [routes, middleware] = await Promise.all([
+    const [routes, middleware, pluginRoutes] = await Promise.all([
       discoverRoutes(this._config.dir),
       discoverMiddleware(this._config.dir),
+      this._pluginManager?.discoverRoutes?.() ?? [],
     ]);
+    routes.push(...pluginRoutes);
 
     applyPrefix(routes, middleware, this._prefix);
 

package/server/router/routes.js

@@ -36,11 +36,21 @@ function matchPattern(items, pathname) {
   return null;
 }
 const compilePattern = compileRoutePattern;
-async function discoverRoutes(apiDir) {
+function normalizeRoutePrefix(rawPrefix) {
+  if (!rawPrefix) return '';
+  return ('/' + rawPrefix.replace(/^\/+|\/+$/g, '')).replace(/^\/$/, '');
+}
+function prefixRoutePattern(pattern, prefix) {
+  const normalized = normalizeRoutePrefix(prefix);
+  if (!normalized) return pattern;
+  if (pattern === '/') return normalized;
+  return normalized + pattern;
+}
+async function discoverRoutes(apiDir, { prefix = '', plugin } = {}) {
   const entries = await discoverModules(apiDir, { recursive: true, label: 'route file' });
   const routes = [];
   for (const { filePath, relativePath, module } of entries) {
-    const urlPattern = filePathToPattern(relativePath);
+    const urlPattern = prefixRoutePattern(filePathToPattern(relativePath), prefix);
     const { regex, paramNames, catchAllParam } = compilePattern(urlPattern);
     for (const method of HTTP_METHODS) {
       const config = module[method];
@@ -66,6 +76,7 @@ async function discoverRoutes(apiDir) {
         paramNames,
         ...(catchAllParam ? { catchAllParam } : {}),
         config,
+        ...(plugin ? { plugin } : {}),
         ...(method === 'GET' && typeof config.ws === 'function' ? { wsEnabled: true } : {}),
       });
     }
@@ -100,5 +111,6 @@ export {
   matchPattern,
   matchRoute,
   matchRoutesByPath,
+  prefixRoutePattern,
   sortBySpecificity,
 };