@forestadmin/agent-bff 1.13.0 → 1.14.0

package/README.md

@@ -5,8 +5,8 @@ agent from a browser without learning MCP or JSON:API.
 
 It is a bootable Koa 3 server with a `/health` endpoint, a version header, env-driven config
 validation, OAuth (Mode 1) + API-key (Mode 2) auth, and a hardened request edge (timezone, CORS,
-auth-mode precedence, structured error contract). The data-endpoint proxy and OpenAPI generation
-land in later slices.
+auth-mode precedence, structured error contract), and it serves and exports its own OpenAPI
+document. The data-endpoint proxy lands in a later slice.
 
 ## Usage
 
@@ -16,6 +16,25 @@ Packaged / production — run the bin:
 forest-bff
 ```
 
+Export the OpenAPI document without booting the server. Needs no configuration, so
+it works in CI to commit the document, diff it, or generate a client:
+
+```bash
+forest-bff openapi > openapi.json          # stdout, redirected
+forest-bff openapi --output                # writes ./openapi.json
+forest-bff openapi --output docs/api.json  # writes that path
+```
+
+`--output` takes the next argument as the destination unless it is empty or starts with
+`-`; the default `openapi.json` is written only when `--output` is the last argument, and
+a leftover token is rejected like any other extra. A missing parent directory is created,
+an existing file is overwritten, and a destination that cannot be written exits 1 with the
+path on stderr. The path is confirmed on stderr, so stdout stays empty and pipeable.
+
+`forest-bff --help` and `forest-bff --version` print to stdout and exit 0, ignoring
+anything that follows. An unknown command, or an argument other than `--output` after
+`openapi`, exits 1 with the reason on stderr.
+
 Local development — copy the env template, fill it in, and start with it loaded:
 
 ```bash

package/dist/cli-dispatch.d.ts

@@ -0,0 +1,12 @@
+import type BFFHttpServer from './http/bff-http-server';
+import type { Logger } from './ports/logger-port';
+export declare const DEFAULT_OUTPUT_FILE = "openapi.json";
+export declare const USAGE = "Usage: forest-bff [command]\n\nCommands:\n  (none)      Start the BFF server, configured from the environment.\n  openapi     Write the OpenAPI document to stdout. Needs no configuration.\n              --output [file]  Write to a file instead of stdout, defaulting\n                               to openapi.json in the current directory.\n\nOptions:\n  -h, --help     Show this help and exit.\n  -v, --version  Show the package version and exit.";
+export declare const HINT = "Run 'forest-bff --help' for usage.";
+export interface DispatchOutcome {
+    exitCode: number;
+    server?: BFFHttpServer;
+}
+export declare function renderOpenApi(): string;
+export default function dispatchCli(argv: string[], env: NodeJS.ProcessEnv, logger?: Logger): Promise<DispatchOutcome>;
+//# sourceMappingURL=cli-dispatch.d.ts.map

package/dist/cli-dispatch.js

@@ -0,0 +1,91 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HINT = exports.USAGE = exports.DEFAULT_OUTPUT_FILE = void 0;
+exports.renderOpenApi = renderOpenApi;
+exports.default = dispatchCli;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const cli_core_1 = __importDefault(require("./cli-core"));
+const errors_1 = require("./errors");
+const openapi_document_1 = require("./openapi/openapi-document");
+const version_1 = __importDefault(require("./version"));
+exports.DEFAULT_OUTPUT_FILE = 'openapi.json';
+const OUTPUT_FLAG = '--output';
+exports.USAGE = `Usage: forest-bff [command]
+
+Commands:
+  (none)      Start the BFF server, configured from the environment.
+  openapi     Write the OpenAPI document to stdout. Needs no configuration.
+              --output [file]  Write to a file instead of stdout, defaulting
+                               to ${exports.DEFAULT_OUTPUT_FILE} in the current directory.
+
+Options:
+  -h, --help     Show this help and exit.
+  -v, --version  Show the package version and exit.`;
+exports.HINT = "Run 'forest-bff --help' for usage.";
+const HELP_FLAGS = new Set(['-h', '--help']);
+const VERSION_FLAGS = new Set(['-v', '--version']);
+function renderOpenApi() {
+    return `${(0, openapi_document_1.serializeOpenApi)((0, openapi_document_1.generateOpenApiDocument)(version_1.default))}\n`;
+}
+function rejectCli(reason) {
+    process.stderr.write(`${reason}\n${exports.HINT}\n`);
+    return { exitCode: 1 };
+}
+function parseOutputOption(rest) {
+    const index = rest.indexOf(OUTPUT_FLAG);
+    if (index === -1)
+        return { extras: rest };
+    const candidate = rest[index + 1];
+    const takesValue = candidate !== undefined && candidate !== '' && !candidate.startsWith('-');
+    return {
+        file: takesValue ? candidate : exports.DEFAULT_OUTPUT_FILE,
+        extras: [...rest.slice(0, index), ...rest.slice(index + (takesValue ? 2 : 1))],
+    };
+}
+function writeOpenApiFile(file) {
+    const asDirectory = file.endsWith('/') || file.endsWith(path_1.default.sep);
+    const destination = path_1.default.resolve(process.cwd(), asDirectory ? path_1.default.join(file, exports.DEFAULT_OUTPUT_FILE) : file);
+    try {
+        (0, fs_1.mkdirSync)(path_1.default.dirname(destination), { recursive: true });
+        (0, fs_1.writeFileSync)(destination, renderOpenApi());
+    }
+    catch (error) {
+        process.stderr.write(`Cannot write ${destination}: ${(0, errors_1.extractErrorMessage)(error)}\n`);
+        return { exitCode: 1 };
+    }
+    process.stderr.write(`Wrote the OpenAPI document to ${destination}\n`);
+    return { exitCode: 0 };
+}
+async function dispatchCli(argv, env, logger) {
+    const [subcommand, ...rest] = argv;
+    if (subcommand === undefined) {
+        return { exitCode: 0, server: await (0, cli_core_1.default)(env, logger) };
+    }
+    if (HELP_FLAGS.has(subcommand)) {
+        process.stdout.write(`${exports.USAGE}\n`);
+        return { exitCode: 0 };
+    }
+    if (VERSION_FLAGS.has(subcommand)) {
+        process.stdout.write(`${version_1.default}\n`);
+        return { exitCode: 0 };
+    }
+    if (subcommand !== 'openapi') {
+        return rejectCli(subcommand === OUTPUT_FLAG
+            ? `${OUTPUT_FLAG} only applies to the openapi command`
+            : `Unknown command: ${subcommand}`);
+    }
+    const { file, extras } = parseOutputOption(rest);
+    if (extras.length > 0) {
+        return rejectCli(`openapi accepts only --output, got: ${extras.map(extra => JSON.stringify(extra)).join(' ')}`);
+    }
+    if (file !== undefined) {
+        return writeOpenApiFile(file);
+    }
+    process.stdout.write(renderOpenApi());
+    return { exitCode: 0 };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xpLWRpc3BhdGNoLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2NsaS1kaXNwYXRjaC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7Ozs7QUFxQ0Esc0NBRUM7QUFnREQsOEJBOENDO0FBbElELDJCQUE4QztBQUM5QyxnREFBd0I7QUFFeEIsMERBQWdDO0FBQ2hDLHFDQUErQztBQUMvQyxpRUFBdUY7QUFDdkYsd0RBQWdDO0FBRW5CLFFBQUEsbUJBQW1CLEdBQUcsY0FBYyxDQUFDO0FBRWxELE1BQU0sV0FBVyxHQUFHLFVBQVUsQ0FBQztBQUVsQixRQUFBLEtBQUssR0FBRzs7Ozs7O29DQU1lLDJCQUFtQjs7OztvREFJSCxDQUFDO0FBRXhDLFFBQUEsSUFBSSxHQUFHLG9DQUFvQyxDQUFDO0FBRXpELE1BQU0sVUFBVSxHQUFHLElBQUksR0FBRyxDQUFDLENBQUMsSUFBSSxFQUFFLFFBQVEsQ0FBQyxDQUFDLENBQUM7QUFDN0MsTUFBTSxhQUFhLEdBQUcsSUFBSSxHQUFHLENBQUMsQ0FBQyxJQUFJLEVBQUUsV0FBVyxDQUFDLENBQUMsQ0FBQztBQU9uRCxTQUFnQixhQUFhO0lBQzNCLE9BQU8sR0FBRyxJQUFBLG1DQUFnQixFQUFDLElBQUEsMENBQXVCLEVBQUMsaUJBQU8sQ0FBQyxDQUFDLElBQUksQ0FBQztBQUNuRSxDQUFDO0FBRUQsU0FBUyxTQUFTLENBQUMsTUFBYztJQUMvQixPQUFPLENBQUMsTUFBTSxDQUFDLEtBQUssQ0FBQyxHQUFHLE1BQU0sS0FBSyxZQUFJLElBQUksQ0FBQyxDQUFDO0lBRTdDLE9BQU8sRUFBRSxRQUFRLEVBQUUsQ0FBQyxFQUFFLENBQUM7QUFDekIsQ0FBQztBQU9ELFNBQVMsaUJBQWlCLENBQUMsSUFBYztJQUN2QyxNQUFNLEtBQUssR0FBRyxJQUFJLENBQUMsT0FBTyxDQUFDLFdBQVcsQ0FBQyxDQUFDO0lBRXhDLElBQUksS0FBSyxLQUFLLENBQUMsQ0FBQztRQUFFLE9BQU8sRUFBRSxNQUFN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

package/dist/cli.js

@@ -1,42 +1,18 @@
 #!/usr/bin/env node
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 /* istanbul ignore file */
-const cli_core_1 = __importStar(require("./cli-core"));
+const cli_core_1 = require("./cli-core");
+const cli_dispatch_1 = __importDefault(require("./cli-dispatch"));
 if (require.main === module) {
-    (0, cli_core_1.default)(process.env).catch(cli_core_1.reportFatalError);
+    (0, cli_dispatch_1.default)(process.argv.slice(2), process.env)
+        .then(({ exitCode }) => {
+        if (exitCode !== 0)
+            process.exitCode = exitCode;
+    })
+        .catch(cli_core_1.reportFatalError);
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xpLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2NsaS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7QUFDQSwwQkFBMEI7QUFDMUIsdURBQXNEO0FBRXRELElBQUksT0FBTyxDQUFDLElBQUksS0FBSyxNQUFNLEVBQUUsQ0FBQztJQUM1QixJQUFBLGtCQUFNLEVBQUMsT0FBTyxDQUFDLEdBQUcsQ0FBQyxDQUFDLEtBQUssQ0FBQywyQkFBZ0IsQ0FBQyxDQUFDO0FBQzlDLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xpLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2NsaS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7Ozs7QUFDQSwwQkFBMEI7QUFDMUIseUNBQThDO0FBQzlDLGtFQUF5QztBQUV6QyxJQUFJLE9BQU8sQ0FBQyxJQUFJLEtBQUssTUFBTSxFQUFFLENBQUM7SUFDNUIsSUFBQSxzQkFBVyxFQUFDLE9BQU8sQ0FBQyxJQUFJLENBQUMsS0FBSyxDQUFDLENBQUMsQ0FBQyxFQUFFLE9BQU8sQ0FBQyxHQUFHLENBQUM7U0FDNUMsSUFBSSxDQUFDLENBQUMsRUFBRSxRQUFRLEVBQUUsRUFBRSxFQUFFO1FBQ3JCLElBQUksUUFBUSxLQUFLLENBQUM7WUFBRSxPQUFPLENBQUMsUUFBUSxHQUFHLFFBQVEsQ0FBQztJQUNsRCxDQUFDLENBQUM7U0FDRCxLQUFLLENBQUMsMkJBQWdCLENBQUMsQ0FBQztBQUM3QixDQUFDIn0=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forestadmin/agent-bff",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "main": "dist/index.js",
   "bin": {
     "forest-bff": "dist/cli.js"