orchajs 0.19.0 → 0.20.0

package/README.md

@@ -763,10 +763,41 @@ they need every judge result to finish and persist.
 
 ### Production and Serverless builds
 
-For esbuild production applications, add `orchaPlugin()` from
-`orchajs/esbuild` to the build that bundles the application handlers. It
-compiles the registry and replaces exact `orchajs` imports with the
-self-contained generated runtime:
+For Serverless Framework projects, install `serverless-esbuild` and register
+the Orcha integration after it:
+
+```bash
+npm install --save-dev serverless-esbuild
+```
+
+```yaml
+plugins:
+  - serverless-esbuild
+  - orchajs/serverless
+```
+
+Serverless Framework v4 users must opt out of its built-in builder before
+loading `serverless-esbuild`:
+
+```yaml
+build:
+  esbuild: false
+```
+
+No separate `orcha build` command or deployment script is required. During
+`serverless package` and `serverless deploy`, the integration adds Orcha to the
+existing esbuild pipeline. It preserves other esbuild plugins, compiles the
+registry, and replaces exact `orchajs` imports with the generated production
+runtime. It rejects configurations that externalize `orchajs`, because those
+would copy the full development package into the Lambda artifact.
+
+`serverless-plugin-typescript` and plain `tsc` do not bundle dependencies.
+Remove that build plugin when switching the service to `serverless-esbuild`.
+Keep `serverless-esbuild` before `orchajs/serverless` and before
+`serverless-offline`.
+
+For non-Serverless esbuild applications, add `orchaPlugin()` from
+`orchajs/esbuild` to the build that bundles the application:
 
 ```js
 const { orchaPlugin } = require("orchajs/esbuild");
@@ -777,11 +808,9 @@ module.exports = {
 };
 ```
 
-For Serverless Framework, use `serverless-esbuild` and point
-`custom.esbuild.config` at that configuration file. Plain TypeScript,
-`serverless-plugin-typescript`, or running `orcha build` separately is not
-enough: `orcha build` creates `.orcha/dist/bundle.js`, but it does not rewrite
-imports in already-built handlers.
+Running `orcha build` separately is not enough: it creates
+`.orcha/dist/bundle.js`, but does not rewrite imports in already-built
+handlers.
 
 Production CI should package the same way as deployment and verify that:
 

package/dist/integrations/serverless.d.ts

@@ -0,0 +1,27 @@
+import type { Plugin } from "esbuild";
+type ServerlessEsbuildOptions = {
+    config?: string;
+    exclude?: string[];
+    external?: string[];
+    plugins?: Plugin[] | string;
+    [key: string]: unknown;
+};
+type ServerlessLike = {
+    config?: {
+        servicePath?: string;
+    };
+    service: {
+        custom?: {
+            esbuild?: ServerlessEsbuildOptions;
+            [key: string]: unknown;
+        };
+        plugins?: string[];
+    };
+};
+export declare class OrchaServerlessPlugin {
+    private readonly serverless;
+    readonly hooks: Record<string, () => void>;
+    constructor(serverless: ServerlessLike);
+    private configureEsbuild;
+}
+export default OrchaServerlessPlugin;

package/dist/integrations/serverless.js

@@ -0,0 +1,78 @@
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import { orchaPlugin } from "./esbuild.js";
+export class OrchaServerlessPlugin {
+    serverless;
+    hooks;
+    constructor(serverless) {
+        this.serverless = serverless;
+        this.hooks = {
+            initialize: () => this.configureEsbuild(),
+        };
+    }
+    configureEsbuild() {
+        const servicePath = resolve(this.serverless.config?.servicePath ?? process.cwd());
+        const configuredPlugins = this.serverless.service.plugins ?? [];
+        if (!configuredPlugins.includes("serverless-esbuild")) {
+            throw new Error('The "orchajs/serverless" plugin requires "serverless-esbuild". Add "serverless-esbuild" before "orchajs/serverless" in the Serverless plugins list.');
+        }
+        const custom = this.serverless.service.custom ?? {};
+        const configuredEsbuild = custom.esbuild ?? {};
+        const esbuild = configuredEsbuild.config
+            ? loadEsbuildConfig(configuredEsbuild.config, servicePath, this.serverless)
+            : { ...configuredEsbuild };
+        assertOrchaIsBundled(esbuild);
+        const existingPlugins = loadEsbuildPlugins(esbuild.plugins, servicePath, this.serverless);
+        if (!existingPlugins.some((plugin) => plugin.name === "orchajs")) {
+            existingPlugins.push(orchaPlugin({ projectRoot: servicePath }));
+        }
+        delete esbuild.config;
+        esbuild.plugins = existingPlugins;
+        custom.esbuild = esbuild;
+        this.serverless.service.custom = custom;
+    }
+}
+function loadEsbuildConfig(configPath, servicePath, serverless) {
+    const loaded = loadProjectModule(configPath, servicePath);
+    const config = unwrapDefault(loaded);
+    if (typeof config !== "function") {
+        throw new Error(`Serverless esbuild config "${configPath}" must export a function.`);
+    }
+    return config(serverless);
+}
+function loadEsbuildPlugins(plugins, servicePath, serverless) {
+    if (!plugins) {
+        return [];
+    }
+    if (Array.isArray(plugins)) {
+        return [...plugins];
+    }
+    const loaded = unwrapDefault(loadProjectModule(plugins, servicePath));
+    const resolved = typeof loaded === "function"
+        ? loaded(serverless)
+        : loaded;
+    if (!Array.isArray(resolved)) {
+        throw new Error(`Serverless esbuild plugins file "${plugins}" must export an array or a function that returns one.`);
+    }
+    return [...resolved];
+}
+function loadProjectModule(path, servicePath) {
+    const requireFromProject = createRequire(resolve(servicePath, "package.json"));
+    return requireFromProject(resolve(servicePath, path));
+}
+function unwrapDefault(value) {
+    if (typeof value === "object" &&
+        value !== null &&
+        "default" in value) {
+        return value.default;
+    }
+    return value;
+}
+function assertOrchaIsBundled(options) {
+    for (const key of ["exclude", "external"]) {
+        if (options[key]?.includes("orchajs")) {
+            throw new Error(`Remove "orchajs" from custom.esbuild.${key}. Orcha must be replaced during bundling, not copied into the Lambda package.`);
+        }
+    }
+}
+export default OrchaServerlessPlugin;

package/dist-cjs/integrations/serverless.cjs

@@ -0,0 +1,2 @@
+"use strict";
+module.exports = require("./serverless.js").OrchaServerlessPlugin;

package/dist-cjs/integrations/serverless.js

@@ -0,0 +1,125 @@
+"use strict"; const __orchaImportMetaUrl = require("url").pathToFileURL(__filename).href;
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var serverless_exports = {};
+__export(serverless_exports, {
+  OrchaServerlessPlugin: () => OrchaServerlessPlugin,
+  default: () => serverless_default
+});
+module.exports = __toCommonJS(serverless_exports);
+var import_module = require("module");
+var import_path = require("path");
+var import_esbuild = require("./esbuild.js");
+class OrchaServerlessPlugin {
+  constructor(serverless) {
+    this.serverless = serverless;
+    this.hooks = {
+      initialize: () => this.configureEsbuild()
+    };
+  }
+  hooks;
+  configureEsbuild() {
+    const servicePath = (0, import_path.resolve)(
+      this.serverless.config?.servicePath ?? process.cwd()
+    );
+    const configuredPlugins = this.serverless.service.plugins ?? [];
+    if (!configuredPlugins.includes("serverless-esbuild")) {
+      throw new Error(
+        'The "orchajs/serverless" plugin requires "serverless-esbuild". Add "serverless-esbuild" before "orchajs/serverless" in the Serverless plugins list.'
+      );
+    }
+    const custom = this.serverless.service.custom ?? {};
+    const configuredEsbuild = custom.esbuild ?? {};
+    const esbuild = configuredEsbuild.config ? loadEsbuildConfig(
+      configuredEsbuild.config,
+      servicePath,
+      this.serverless
+    ) : { ...configuredEsbuild };
+    assertOrchaIsBundled(esbuild);
+    const existingPlugins = loadEsbuildPlugins(
+      esbuild.plugins,
+      servicePath,
+      this.serverless
+    );
+    if (!existingPlugins.some((plugin) => plugin.name === "orchajs")) {
+      existingPlugins.push((0, import_esbuild.orchaPlugin)({ projectRoot: servicePath }));
+    }
+    delete esbuild.config;
+    esbuild.plugins = existingPlugins;
+    custom.esbuild = esbuild;
+    this.serverless.service.custom = custom;
+  }
+}
+function loadEsbuildConfig(configPath, servicePath, serverless) {
+  const loaded = loadProjectModule(
+    configPath,
+    servicePath
+  );
+  const config = unwrapDefault(loaded);
+  if (typeof config !== "function") {
+    throw new Error(
+      `Serverless esbuild config "${configPath}" must export a function.`
+    );
+  }
+  return config(serverless);
+}
+function loadEsbuildPlugins(plugins, servicePath, serverless) {
+  if (!plugins) {
+    return [];
+  }
+  if (Array.isArray(plugins)) {
+    return [...plugins];
+  }
+  const loaded = unwrapDefault(
+    loadProjectModule(plugins, servicePath)
+  );
+  const resolved = typeof loaded === "function" ? loaded(serverless) : loaded;
+  if (!Array.isArray(resolved)) {
+    throw new Error(
+      `Serverless esbuild plugins file "${plugins}" must export an array or a function that returns one.`
+    );
+  }
+  return [...resolved];
+}
+function loadProjectModule(path, servicePath) {
+  const requireFromProject = (0, import_module.createRequire)(
+    (0, import_path.resolve)(servicePath, "package.json")
+  );
+  return requireFromProject((0, import_path.resolve)(servicePath, path));
+}
+function unwrapDefault(value) {
+  if (typeof value === "object" && value !== null && "default" in value) {
+    return value.default;
+  }
+  return value;
+}
+function assertOrchaIsBundled(options) {
+  for (const key of ["exclude", "external"]) {
+    if (options[key]?.includes("orchajs")) {
+      throw new Error(
+        `Remove "orchajs" from custom.esbuild.${key}. Orcha must be replaced during bundling, not copied into the Lambda package.`
+      );
+    }
+  }
+}
+var serverless_default = OrchaServerlessPlugin;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  OrchaServerlessPlugin
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchajs",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "A filesystem-convention, stateful agent framework for JavaScript.",
   "license": "MIT",
   "repository": {
@@ -31,6 +31,11 @@
       "import": "./dist/integrations/esbuild.js",
       "require": "./dist-cjs/integrations/esbuild.js"
     },
+    "./serverless": {
+      "types": "./dist/integrations/serverless.d.ts",
+      "import": "./dist/integrations/serverless.js",
+      "require": "./dist-cjs/integrations/serverless.cjs"
+    },
     "./testing": {
       "types": "./dist/testing.d.ts",
       "import": "./dist/testing.js",
@@ -42,6 +47,9 @@
       "esbuild": [
         "dist/integrations/esbuild.d.ts"
       ],
+      "serverless": [
+        "dist/integrations/serverless.d.ts"
+      ],
       "testing": [
         "dist/testing.d.ts"
       ]