@qodalis/cli-server-node 1.0.0-beta.1 → 1.0.0-beta.10

package/dist/src/create-cli-server.d.ts

@@ -0,0 +1,123 @@
+import { Express, Router } from 'express';
+import cors from 'cors';
+import { CliCommandRegistry, CliCommandExecutorService, CliEventSocketManager, CliLogSocketManager } from './services';
+import { CliBuilder } from './extensions';
+import { ICliServerAuth } from './auth/cli-server-auth';
+import { CliShellOptions } from './services/cli-shell-options';
+import { CliMcpOptions, McpToolProvider } from './mcp';
+/**
+ * Generic interface for plugin results that can be auto-mounted.
+ * Plugins expose a `prefix` and `router`; some also have a
+ * `dashboardPrefix` / `dashboardRouter` pair.
+ */
+export interface MountablePlugin {
+    prefix: string;
+    router: Router;
+    dashboardPrefix?: string;
+    dashboardRouter?: Router;
+    /**
+     * Auth provider exposed by the users plugin. Mounting such a plugin
+     * installs it: when `protectServer` is on, every server route and socket
+     * then requires a users session.
+     */
+    serverAuth?: ICliServerAuth;
+    /** Routes that stay public under server protection, as `"METHOD /path"` (e.g. a plugin's login). */
+    publicRoutes?: string[];
+    /** MCP tool providers contributed by the plugin (used when the `mcp` option is on). */
+    mcpProviders?: McpToolProvider[];
+    /** Job scheduler (the jobs plugin): enables the `jobs_*` MCP tools. */
+    scheduler?: unknown;
+}
+/** MCP extension point of a server instance. */
+export interface CliServerMcp {
+    /** True when the MCP endpoint is enabled. */
+    readonly enabled: boolean;
+    /** The endpoint path (`{basePath}/mcp`). */
+    readonly path: string;
+    /**
+     * Registers a tool provider. On a name collision built-in feature tools win,
+     * then providers in registration order, then command tools.
+     */
+    addProvider(provider: McpToolProvider): void;
+}
+/** Options for creating a standalone CLI server instance. */
+export interface CliServerOptions {
+    /** Base path for CLI routes. Defaults to '/api/qcli'. */
+    basePath?: string;
+    /**
+     * CORS configuration. `true` = permissive (any origin, no credentials),
+     * `false` = disabled, or a cors options object. When omitted, CORS is
+     * enabled only for `allowedOrigins` (disabled if none are set).
+     */
+    cors?: boolean | cors.CorsOptions;
+    /**
+     * Origins allowed for CORS and WebSocket upgrades (exact match; `http://host:*`
+     * matches any port). Every WS upgrade with an `Origin` header is checked.
+     */
+    allowedOrigins?: string[];
+    /**
+     * Accept interactive shell WebSocket sessions (default false). When enabled,
+     * access is decided by one mode: users plugin mounted (ticket +
+     * `shell:execute`), `shell.token`, `shell.authorize` or `shell.allowAnonymous`.
+     * With none of them the shell is locked (every connection closed with 4401).
+     */
+    enableShell?: boolean;
+    /** Remote shell security: access mode, limits, timeouts, cwd, shell binary, environment. */
+    shell?: CliShellOptions;
+    /**
+     * Behind reverse proxies: the number of trusted proxy hops (`true` = 1,
+     * `false`/0 = none, the default). The client IP (Express `req.ip`, the
+     * shell's per-address limits) is the `X-Forwarded-For` entry at index
+     * `len - hops` (with one hop, the rightmost entry, appended by the trusted
+     * proxy); the leftmost entry when the list is shorter, the socket address
+     * when the header is absent. `X-Forwarded-Proto`/`-Host` are honoured too.
+     */
+    trustProxy?: boolean | number;
+    /**
+     * Auth provider protecting the whole server (e.g. `usersPlugin.serverAuth`).
+     * Can also be installed later with `setAuth()` or by `mountPlugin(usersPlugin)`.
+     */
+    auth?: ICliServerAuth;
+    /**
+     * MCP endpoint (`POST {basePath}/mcp`, off by default): AI clients call the
+     * registered commands as MCP tools. `true` enables it with defaults; the object
+     * form sets an allow/deny list of tools, a static bearer `token` (only without
+     * an auth provider) and `instructions` returned by `initialize`.
+     */
+    mcp?: boolean | CliMcpOptions;
+    /** Configure processors via the builder. */
+    configure?: (builder: CliBuilder) => void;
+}
+/**
+ * Creates a fully configured Express app with CLI routes mounted.
+ *
+ * Use this for standalone server mode. For integration into an existing
+ * Express app, use `createCliController` directly instead.
+ */
+export interface CliServerResult {
+    app: Express;
+    registry: CliCommandRegistry;
+    builder: CliBuilder;
+    executor: CliCommandExecutorService;
+    eventSocketManager: CliEventSocketManager;
+    logSocketManager: CliLogSocketManager;
+    /**
+     * Mount a plugin using its built-in prefix.
+     * Reads `prefix` and `router` from the plugin result, and optionally
+     * `dashboardPrefix` / `dashboardRouter` for plugins that serve a UI.
+     *
+     * @example
+     * ```ts
+     * const result = createCliServer();
+     * result.mountPlugin(jobsPlugin);
+     * result.mountPlugin(adminPlugin);
+     * ```
+     */
+    mountPlugin(plugin: MountablePlugin): void;
+    /** Installs (or removes) the auth provider protecting server routes and sockets. */
+    setAuth(auth: ICliServerAuth | undefined): void;
+    /** MCP endpoint: register tool providers (`mcp.addProvider(p)`). */
+    mcp: CliServerMcp;
+}
+export declare function createCliServer(options?: CliServerOptions): CliServerResult;
+//# sourceMappingURL=create-cli-server.d.ts.map

package/dist/src/create-cli-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-cli-server.d.ts","sourceRoot":"","sources":["../../src/create-cli-server.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACvH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAO1C,OAAO,EAAE,cAAc,EAAmD,MAAM,wBAAwB,CAAC;AAEzG,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAE/D,OAAO,EACH,aAAa,EAKb,eAAe,EAOlB,MAAM,OAAO,CAAC;AAGf;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,oGAAoG;IACpG,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,uFAAuF;IACvF,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC;IACjC,uEAAuE;IACvE,SAAS,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,gDAAgD;AAChD,MAAM,WAAW,YAAY;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;CAChD;AAID,6DAA6D;AAC7D,MAAM,WAAW,gBAAgB;IAC7B,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC;IAClC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4FAA4F;IAC5F,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC9B;;;OAGG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAC9B,4CAA4C;IAC5C,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,CAAC;CAC7C;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC5B,GAAG,EAAE,OAAO,CAAC;IACb,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,UAAU,CAAC;IACpB,QAAQ,EAAE,yBAAyB,CAAC;IACpC,kBAAkB,EAAE,qBAAqB,CAAC;IAC1C,gBAAgB,EAAE,mBAAmB,CAAC;IACtC;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;IAC3C,oFAAoF;IACpF,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,GAAG,IAAI,CAAC;IAChD,oEAAoE;IACpE,GAAG,EAAE,YAAY,CAAC;CACrB;AAED,wBAAgB,eAAe,CAAC,OAAO,GAAE,gBAAqB,GAAG,eAAe,CAmM/E"}

package/dist/src/create-cli-server.js

@@ -0,0 +1,201 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCliServer = createCliServer;
+const express_1 = __importDefault(require("express"));
+const cors_1 = __importDefault(require("cors"));
+const services_1 = require("./services");
+const extensions_1 = require("./extensions");
+const cli_controller_1 = require("./controllers/cli-controller");
+const cli_version_controller_1 = require("./controllers/cli-version-controller");
+const filesystem_controller_1 = require("./controllers/filesystem-controller");
+const cli_server_plugin_filesystem_1 = require("@qodalis/cli-server-plugin-filesystem");
+const cli_server_plugin_data_explorer_1 = require("@qodalis/cli-server-plugin-data-explorer");
+const logger_1 = require("./utils/logger");
+const cli_server_auth_1 = require("./auth/cli-server-auth");
+const cli_server_auth_gate_1 = require("./auth/cli-server-auth-gate");
+const mcp_1 = require("./mcp");
+const logger = (0, logger_1.createLogger)('Server');
+function createCliServer(options = {}) {
+    const { basePath = '/api/qcli', cors: corsOption, configure, allowedOrigins, enableShell = false, shell, trustProxy = false } = options;
+    if (shell && !enableShell) {
+        logger.warn('shell options are set but enableShell is false: the shell stays disabled');
+    }
+    const app = (0, express_1.default)();
+    const proxyHops = (0, cli_server_auth_1.trustedProxyHops)(trustProxy);
+    if (proxyHops > 0) {
+        app.set('trust proxy', proxyHops);
+    }
+    if (corsOption === true) {
+        app.use((0, cors_1.default)());
+    }
+    else if (corsOption && typeof corsOption === 'object') {
+        app.use((0, cors_1.default)(corsOption));
+    }
+    else if (corsOption === undefined && allowedOrigins && allowedOrigins.length > 0) {
+        // Same-origin requests (e.g. the bundled admin dashboard) are always allowed.
+        app.use((0, cors_1.default)((req, callback) => {
+            const origin = req.headers.origin;
+            callback(null, {
+                origin: (0, cli_server_auth_1.isOriginAllowed)(origin, allowedOrigins) || (0, cli_server_auth_1.isSameOrigin)(origin, req),
+            });
+        }));
+    }
+    const mcpOptions = (0, mcp_1.resolveMcpOptions)(options.mcp);
+    const mcpPath = `${(0, cli_server_auth_gate_1.normalizePath)(basePath)}/mcp`;
+    if (mcpOptions?.token && options.auth?.protectServer) {
+        logger.warn('mcp.token is ignored: the auth provider protects the MCP endpoint');
+    }
+    if (mcpOptions) {
+        // DNS-rebinding protection and 405s come first, before authentication
+        app.use(mcpPath, (0, mcp_1.createMcpPreGate)({ allowedOrigins, trustProxy }));
+    }
+    // The MCP endpoint reads its own body (JSON-RPC parse errors are JSON-RPC responses)
+    const jsonParser = express_1.default.json({ limit: '1mb' });
+    app.use((req, res, next) => {
+        if (mcpOptions && (0, cli_server_auth_gate_1.normalizePath)(req.path) === mcpPath) {
+            next();
+            return;
+        }
+        jsonParser(req, res, next);
+    });
+    // Render body-parser failures (malformed JSON, too large) as JSON `{ error }`
+    app.use((err, _req, res, next) => {
+        if (err && (err.type === 'entity.parse.failed' || err.type === 'entity.too.large')) {
+            const status = err.type === 'entity.too.large' ? 413 : 400;
+            res.status(status).json({ error: status === 413 ? 'request body too large' : 'invalid JSON body' });
+            return;
+        }
+        next(err);
+    });
+    const registry = new services_1.CliCommandRegistry();
+    const builder = new extensions_1.CliBuilder(registry);
+    // Server-wide auth gate (no-op until an auth provider is installed)
+    let serverAuth;
+    const publicRoutes = new Set();
+    app.use((0, cli_server_auth_gate_1.createServerAuthGate)(() => serverAuth, {
+        registry,
+        cliPrefixes: Array.from(new Set(['/api/v1/qcli', (0, cli_server_auth_gate_1.normalizePath)(basePath)])),
+        publicRoutes,
+        mcpPaths: mcpOptions ? [mcpPath] : [],
+    }));
+    if (configure) {
+        configure(builder);
+    }
+    const executor = new services_1.CliCommandExecutorService(registry);
+    const eventSocketManager = new services_1.CliEventSocketManager({ enableShell, shell, allowedOrigins, trustProxy });
+    const logSocketManager = new services_1.CliLogSocketManager({ allowedOrigins, trustProxy });
+    const shellCapabilities = () => {
+        const mode = eventSocketManager.shellAuthMode;
+        return mode ? { shell: true, shellAuth: mode } : { shell: false };
+    };
+    // MCP tool providers, in priority order: built-in features, plugins/host (registration order), then commands
+    const mcpFeatureProviders = [];
+    const commandsMcpProvider = new mcp_1.CommandsMcpToolProvider(registry, executor);
+    const mcpFeatures = new Set(['commands']);
+    if (mcpOptions) {
+        mcpFeatures.add('mcp');
+        mcpFeatureProviders.push(new mcp_1.ServerMcpToolProvider({
+            registry,
+            serverName: mcp_1.MCP_SERVER_NAME,
+            version: mcp_1.MCP_SERVER_VERSION,
+            capabilities: () => ({ ...shellCapabilities() }),
+            features: () => {
+                const features = [...mcpFeatures];
+                if (eventSocketManager.shellAuthMode)
+                    features.push('shell');
+                if (serverAuth?.protectServer)
+                    features.push('users');
+                return features;
+            },
+        }));
+        app.use(mcpPath, (0, mcp_1.createMcpController)({
+            providers: () => [...mcpFeatureProviders, ...builder.mcpToolProviders, commandsMcpProvider],
+            mcp: mcpOptions,
+            getAuth: () => serverAuth,
+            allowedOrigins,
+            trustProxy,
+        }));
+    }
+    // Version discovery endpoint
+    app.use('/api/qcli', (0, cli_version_controller_1.createCliVersionController)({ shellCapabilities }));
+    // API v1 routes
+    app.use('/api/v1/qcli', (0, cli_controller_1.createCliController)(registry, executor, { shellCapabilities }));
+    // Custom basePath fallback (when user overrides the default)
+    if (basePath !== '/api/v1/qcli') {
+        app.use(basePath, (0, cli_controller_1.createCliController)(registry, executor, { shellCapabilities }));
+    }
+    // Filesystem API — provider-based
+    let fsProvider = builder.fileStorageProvider;
+    if (!fsProvider && builder.fileSystemOptions) {
+        // Backward compatibility: create OsFileStorageProvider from old-style options
+        fsProvider = new cli_server_plugin_filesystem_1.OsFileStorageProvider(builder.fileSystemOptions);
+    }
+    if (fsProvider) {
+        app.use('/api/qcli/fs', (0, filesystem_controller_1.createFilesystemRouter)(fsProvider, builder.fileSystemApiOptions));
+        mcpFeatureProviders.push(new mcp_1.FilesystemMcpToolProvider(fsProvider));
+        mcpFeatures.add('filesystem');
+    }
+    // Data Explorer API
+    const deBuilder = builder.dataExplorerBuilder;
+    if (deBuilder && deBuilder.registry.size > 0) {
+        const deExecutor = new cli_server_plugin_data_explorer_1.DataExplorerExecutor(deBuilder.registry);
+        app.use('/api/qcli/data-explorer', (0, cli_server_plugin_data_explorer_1.createDataExplorerController)(deBuilder.registry, deExecutor));
+        mcpFeatureProviders.push(new mcp_1.DataExplorerMcpToolProvider(deBuilder.registry, deExecutor));
+        mcpFeatures.add('data-explorer');
+    }
+    logger.info('CLI server created with %d processors', registry.processors.length);
+    const setAuth = (auth) => {
+        serverAuth = auth;
+        eventSocketManager.setAuth(auth);
+        logSocketManager.setAuth(auth);
+        auth?.attachToServer?.({
+            allowedOrigins,
+            broadcast: (msg) => eventSocketManager.broadcastMessage(msg),
+        });
+    };
+    if (options.auth) {
+        setAuth(options.auth);
+    }
+    const mountPlugin = (plugin) => {
+        for (const route of plugin.publicRoutes ?? []) {
+            const [method, ...rest] = route.trim().split(/\s+/);
+            publicRoutes.add(`${method.toUpperCase()} ${(0, cli_server_auth_gate_1.normalizePath)(rest.join(' '))}`);
+        }
+        if (plugin.serverAuth && plugin.serverAuth !== serverAuth) {
+            setAuth(plugin.serverAuth);
+        }
+        app.use(plugin.prefix, plugin.router);
+        if (plugin.dashboardPrefix && plugin.dashboardRouter) {
+            app.use(plugin.dashboardPrefix, plugin.dashboardRouter);
+        }
+        if (isJobScheduler(plugin.scheduler) && !mcpFeatures.has('jobs')) {
+            mcpFeatureProviders.push(new mcp_1.JobsMcpToolProvider(plugin.scheduler));
+            mcpFeatures.add('jobs');
+        }
+        for (const provider of plugin.mcpProviders ?? []) {
+            builder.addMcpToolProvider(provider);
+        }
+    };
+    const mcp = {
+        enabled: !!mcpOptions,
+        path: mcpPath,
+        addProvider: (provider) => {
+            builder.addMcpToolProvider(provider);
+        },
+    };
+    return { app, registry, builder, executor, eventSocketManager, logSocketManager, mountPlugin, setAuth, mcp };
+}
+/** Duck-typed check (the jobs plugin may be a different package copy than the server's). */
+function isJobScheduler(value) {
+    const s = value;
+    return (!!s &&
+        typeof s.getAll === 'function' &&
+        typeof s.get === 'function' &&
+        typeof s.getRegistration === 'function' &&
+        typeof s.triggerAsync === 'function' &&
+        typeof s.cancelCurrentAsync === 'function');
+}
+//# sourceMappingURL=create-cli-server.js.map

package/dist/src/create-cli-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-cli-server.js","sourceRoot":"","sources":["../../src/create-cli-server.ts"],"names":[],"mappings":";;;;;AAsJA,0CAmMC;AAzVD,sDAAmD;AACnD,gDAAwB;AACxB,yCAAuH;AACvH,6CAA0C;AAC1C,iEAAmE;AACnE,iFAAkF;AAClF,+EAA6E;AAC7E,wFAA8E;AAC9E,8FAA8G;AAC9G,2CAA8C;AAC9C,4DAAyG;AACzG,sEAAkF;AAGlF,+BAae;AAwCf,MAAM,MAAM,GAAG,IAAA,qBAAY,EAAC,QAAQ,CAAC,CAAC;AAmFtC,SAAgB,eAAe,CAAC,UAA4B,EAAE;IAC1D,MAAM,EAAE,QAAQ,GAAG,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,cAAc,EAAE,WAAW,GAAG,KAAK,EAAE,KAAK,EAAE,UAAU,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;IACxI,IAAI,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC;QACxB,MAAM,CAAC,IAAI,CAAC,0EAA0E,CAAC,CAAC;IAC5F,CAAC;IAED,MAAM,GAAG,GAAG,IAAA,iBAAO,GAAE,CAAC;IACtB,MAAM,SAAS,GAAG,IAAA,kCAAgB,EAAC,UAAU,CAAC,CAAC;IAC/C,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;QAChB,GAAG,CAAC,GAAG,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QACtB,GAAG,CAAC,GAAG,CAAC,IAAA,cAAI,GAAE,CAAC,CAAC;IACpB,CAAC;SAAM,IAAI,UAAU,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE,CAAC;QACtD,GAAG,CAAC,GAAG,CAAC,IAAA,cAAI,EAAC,UAAU,CAAC,CAAC,CAAC;IAC9B,CAAC;SAAM,IAAI,UAAU,KAAK,SAAS,IAAI,cAAc,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjF,8EAA8E;QAC9E,GAAG,CAAC,GAAG,CACH,IAAA,cAAI,EAAC,CAAC,GAAG,EAAE,QAAQ,EAAE,EAAE;YACnB,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC;YAClC,QAAQ,CAAC,IAAI,EAAE;gBACX,MAAM,EAAE,IAAA,iCAAe,EAAC,MAAM,EAAE,cAAc,CAAC,IAAI,IAAA,8BAAY,EAAC,MAAM,EAAE,GAAsB,CAAC;aAClG,CAAC,CAAC;QACP,CAAC,CAAC,CACL,CAAC;IACN,CAAC;IAED,MAAM,UAAU,GAAG,IAAA,uBAAiB,EAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAClD,MAAM,OAAO,GAAG,GAAG,IAAA,oCAAa,EAAC,QAAQ,CAAC,MAAM,CAAC;IACjD,IAAI,UAAU,EAAE,KAAK,IAAI,OAAO,CAAC,IAAI,EAAE,aAAa,EAAE,CAAC;QACnD,MAAM,CAAC,IAAI,CAAC,mEAAmE,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,UAAU,EAAE,CAAC;QACb,sEAAsE;QACtE,GAAG,CAAC,GAAG,CAAC,OAAO,EAAE,IAAA,sBAAgB,EAAC,EAAE,cAAc,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC;IACvE,CAAC;IAED,qFAAqF;IACrF,MAAM,UAAU,GAAG,iBAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAClD,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QACvB,IAAI,UAAU,IAAI,IAAA,oCAAa,EAAC,GAAG,CAAC,IAAI,CAAC,KAAK,OAAO,EAAE,CAAC;YACpD,IAAI,EAAE,CAAC;YACP,OAAO;QACX,CAAC;QACD,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;IACH,8EAA8E;IAC9E,GAAG,CAAC,GAAG,CAAC,CAAC,GAAQ,EAAE,IAAqB,EAAE,GAAqB,EAAE,IAA0B,EAAE,EAAE;QAC3F,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK,qBAAqB,IAAI,GAAG,CAAC,IAAI,KAAK,kBAAkB,CAAC,EAAE,CAAC;YACjF,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,KAAK,kBAAkB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;YAC3D,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,mBAAmB,EAAE,CAAC,CAAC;YACpG,OAAO;QACX,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,CAAC;IACd,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,IAAI,6BAAkB,EAAE,CAAC;IAC1C,MAAM,OAAO,GAAG,IAAI,uBAAU,CAAC,QAAQ,CAAC,CAAC;IAEzC,oEAAoE;IACpE,IAAI,UAAsC,CAAC;IAC3C,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,GAAG,CAAC,GAAG,CACH,IAAA,2CAAoB,EAAC,GAAG,EAAE,CAAC,UAAU,EAAE;QACnC,QAAQ;QACR,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,cAAc,EAAE,IAAA,oCAAa,EAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QAC3E,YAAY;QACZ,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE;KACxC,CAAC,CACL,CAAC;IAEF,IAAI,SAAS,EAAE,CAAC;QACZ,SAAS,CAAC,OAAO,CAAC,CAAC;IACvB,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,oCAAyB,CAAC,QAAQ,CAAC,CAAC;IAEzD,MAAM,kBAAkB,GAAG,IAAI,gCAAqB,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,CAAC,CAAC;IACzG,MAAM,gBAAgB,GAAG,IAAI,8BAAmB,CAAC,EAAE,cAAc,EAAE,UAAU,EAAE,CAAC,CAAC;IACjF,MAAM,iBAAiB,GAAG,GAAsB,EAAE;QAC9C,MAAM,IAAI,GAAG,kBAAkB,CAAC,aAAa,CAAC;QAC9C,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACtE,CAAC,CAAC;IAEF,6GAA6G;IAC7G,MAAM,mBAAmB,GAAsB,EAAE,CAAC;IAClD,MAAM,mBAAmB,GAAG,IAAI,6BAAuB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC5E,MAAM,WAAW,GAAG,IAAI,GAAG,CAAS,CAAC,UAAU,CAAC,CAAC,CAAC;IAClD,IAAI,UAAU,EAAE,CAAC;QACb,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACvB,mBAAmB,CAAC,IAAI,CACpB,IAAI,2BAAqB,CAAC;YACtB,QAAQ;YACR,UAAU,EAAE,qBAAe;YAC3B,OAAO,EAAE,wBAAkB;YAC3B,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,iBAAiB,EAAE,EAAE,CAAC;YAChD,QAAQ,EAAE,GAAG,EAAE;gBACX,MAAM,QAAQ,GAAG,CAAC,GAAG,WAAW,CAAC,CAAC;gBAClC,IAAI,kBAAkB,CAAC,aAAa;oBAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAC7D,IAAI,UAAU,EAAE,aAAa;oBAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACtD,OAAO,QAAQ,CAAC;YACpB,CAAC;SACJ,CAAC,CACL,CAAC;QACF,GAAG,CAAC,GAAG,CACH,OAAO,EACP,IAAA,yBAAmB,EAAC;YAChB,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,mBAAmB,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,mBAAmB,CAAC;YAC3F,GAAG,EAAE,UAAU;YACf,OAAO,EAAE,GAAG,EAAE,CAAC,UAAU;YACzB,cAAc;YACd,UAAU;SACb,CAAC,CACL,CAAC;IACN,CAAC;IAED,6BAA6B;IAC7B,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,IAAA,mDAA0B,EAAC,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC;IAExE,gBAAgB;IAChB,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,IAAA,oCAAmB,EAAC,QAAQ,EAAE,QAAQ,EAAE,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC;IAExF,6DAA6D;IAC7D,IAAI,QAAQ,KAAK,cAAc,EAAE,CAAC;QAC9B,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAA,oCAAmB,EAAC,QAAQ,EAAE,QAAQ,EAAE,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC;IACtF,CAAC;IAED,kCAAkC;IAClC,IAAI,UAAU,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAC7C,IAAI,CAAC,UAAU,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;QAC3C,8EAA8E;QAC9E,UAAU,GAAG,IAAI,oDAAqB,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,UAAU,EAAE,CAAC;QACb,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,IAAA,8CAAsB,EAAC,UAAU,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC;QAC1F,mBAAmB,CAAC,IAAI,CAAC,IAAI,+BAAyB,CAAC,UAAU,CAAC,CAAC,CAAC;QACpE,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAClC,CAAC;IAED,oBAAoB;IACpB,MAAM,SAAS,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAC9C,IAAI,SAAS,IAAI,SAAS,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;QAC3C,MAAM,UAAU,GAAG,IAAI,sDAAoB,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAChE,GAAG,CAAC,GAAG,CAAC,yBAAyB,EAAE,IAAA,8DAA4B,EAAC,SAAS,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC;QACjG,mBAAmB,CAAC,IAAI,CAAC,IAAI,iCAA2B,CAAC,SAAS,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC;QAC1F,WAAW,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACrC,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,uCAAuC,EAAE,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IAEjF,MAAM,OAAO,GAAG,CAAC,IAAgC,EAAE,EAAE;QACjD,UAAU,GAAG,IAAI,CAAC;QAClB,kBAAkB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACjC,gBAAgB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,EAAE,cAAc,EAAE,CAAC;YACnB,cAAc;YACd,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,GAAG,CAAC;SAC/D,CAAC,CAAC;IACP,CAAC,CAAC;IAEF,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACf,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,MAAM,WAAW,GAAG,CAAC,MAAuB,EAAE,EAAE;QAC5C,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,YAAY,IAAI,EAAE,EAAE,CAAC;YAC5C,MAAM,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACpD,YAAY,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,WAAW,EAAE,IAAI,IAAA,oCAAa,EAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;QACjF,CAAC;QACD,IAAI,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;YACxD,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC/B,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QACtC,IAAI,MAAM,CAAC,eAAe,IAAI,MAAM,CAAC,eAAe,EAAE,CAAC;YACnD,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,eAAe,CAAC,CAAC;QAC5D,CAAC;QACD,IAAI,cAAc,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC/D,mBAAmB,CAAC,IAAI,CAAC,IAAI,yBAAmB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;YACpE,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC;QACD,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,YAAY,IAAI,EAAE,EAAE,CAAC;YAC/C,OAAO,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC;QACzC,CAAC;IACL,CAAC,CAAC;IAEF,MAAM,GAAG,GAAiB;QACtB,OAAO,EAAE,CAAC,CAAC,UAAU;QACrB,IAAI,EAAE,OAAO;QACb,WAAW,EAAE,CAAC,QAAQ,EAAE,EAAE;YACtB,OAAO,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC;QACzC,CAAC;KACJ,CAAC;IAEF,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;AACjH,CAAC;AAED,4FAA4F;AAC5F,SAAS,cAAc,CAAC,KAAc;IAClC,MAAM,CAAC,GAAG,KAAoE,CAAC;IAC/E,OAAO,CACH,CAAC,CAAC,CAAC;QACH,OAAO,CAAC,CAAC,MAAM,KAAK,UAAU;QAC9B,OAAO,CAAC,CAAC,GAAG,KAAK,UAAU;QAC3B,OAAO,CAAC,CAAC,eAAe,KAAK,UAAU;QACvC,OAAO,CAAC,CAAC,YAAY,KAAK,UAAU;QACpC,OAAO,CAAC,CAAC,kBAAkB,KAAK,UAAU,CAC7C,CAAC;AACN,CAAC"}

package/dist/src/extensions/cli-builder.d.ts

@@ -0,0 +1,54 @@
+import { ICliCommandProcessor, ICliModule, IDataExplorerProvider, DataExplorerProviderOptions } from '../abstractions';
+import { FileSystemApiOptions, FileSystemOptions } from '../filesystem';
+import { IFileStorageProvider } from '@qodalis/cli-server-plugin-filesystem';
+import { DataExplorerBuilder, DataExplorerProviderFactory } from '@qodalis/cli-server-plugin-data-explorer';
+import { CliCommandRegistry } from '../services';
+import type { McpToolProvider } from '../mcp/mcp-types';
+/**
+ * Fluent builder for configuring CLI server processors, modules, filesystem, and data explorer providers.
+ * Passed to the `configure` callback in {@link CliServerOptions}.
+ */
+export declare class CliBuilder {
+    private readonly _registry;
+    private readonly _modules;
+    private _fileSystemOptions?;
+    private _fileStorageProvider?;
+    private _fileSystemApiOptions;
+    private _dataExplorerBuilder?;
+    private readonly _mcpToolProviders;
+    constructor(registry: CliCommandRegistry);
+    /** Registers a single command processor. */
+    addProcessor(processor: ICliCommandProcessor): CliBuilder;
+    /** Registers a module and all of its command processors. */
+    addModule(module: ICliModule): CliBuilder;
+    /** Returns all registered modules. */
+    get modules(): ReadonlyArray<ICliModule>;
+    /** Configures the filesystem API with path-based access control (and `maxUploadBytes`). */
+    addFileSystem(options: FileSystemOptions): CliBuilder;
+    /** Returns the underlying command registry. */
+    get registry(): CliCommandRegistry;
+    /**
+     * Sets a custom file storage provider for the filesystem API. `options`
+     * configures the HTTP API (e.g. `maxUploadBytes`, default 100 MiB).
+     */
+    setFileStorageProvider(provider: IFileStorageProvider, options?: FileSystemApiOptions): CliBuilder;
+    /** Options of the filesystem HTTP API (`maxUploadBytes`). */
+    get fileSystemApiOptions(): FileSystemApiOptions;
+    /** Returns the configured filesystem options, if any. */
+    get fileSystemOptions(): FileSystemOptions | undefined;
+    /** Returns the configured file storage provider, if any. */
+    get fileStorageProvider(): IFileStorageProvider | undefined;
+    /** Registers a data explorer provider with its configuration options. */
+    addDataExplorerProvider(providerOrFactory: IDataExplorerProvider | DataExplorerProviderFactory, options: DataExplorerProviderOptions): CliBuilder;
+    /** Returns the data explorer builder, if any providers have been registered. */
+    get dataExplorerBuilder(): DataExplorerBuilder | undefined;
+    /**
+     * Registers an MCP tool provider (used when the server's `mcp` option is on).
+     * On a name collision built-in feature tools win, then providers in registration
+     * order, then command tools.
+     */
+    addMcpToolProvider(provider: McpToolProvider): CliBuilder;
+    /** MCP tool providers registered by plugins and the host, in registration order. */
+    get mcpToolProviders(): ReadonlyArray<McpToolProvider>;
+}
+//# sourceMappingURL=cli-builder.d.ts.map

package/dist/src/extensions/cli-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-builder.d.ts","sourceRoot":"","sources":["../../../src/extensions/cli-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAE,qBAAqB,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAC;AACvH,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,MAAM,0CAA0C,CAAC;AAC5G,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD;;;GAGG;AACH,qBAAa,UAAU;IACnB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAC7C,OAAO,CAAC,kBAAkB,CAAC,CAAoB;IAC/C,OAAO,CAAC,oBAAoB,CAAC,CAAuB;IACpD,OAAO,CAAC,qBAAqB,CAA4B;IACzD,OAAO,CAAC,oBAAoB,CAAC,CAAsB;IACnD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAyB;gBAE/C,QAAQ,EAAE,kBAAkB;IAIxC,4CAA4C;IAC5C,YAAY,CAAC,SAAS,EAAE,oBAAoB,GAAG,UAAU;IAKzD,4DAA4D;IAC5D,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU;IAQzC,sCAAsC;IACtC,IAAI,OAAO,IAAI,aAAa,CAAC,UAAU,CAAC,CAEvC;IAED,2FAA2F;IAC3F,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU;IAMrD,+CAA+C;IAC/C,IAAI,QAAQ,IAAI,kBAAkB,CAEjC;IAED;;;OAGG;IACH,sBAAsB,CAAC,QAAQ,EAAE,oBAAoB,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,UAAU;IAQlG,6DAA6D;IAC7D,IAAI,oBAAoB,IAAI,oBAAoB,CAE/C;IAED,yDAAyD;IACzD,IAAI,iBAAiB,IAAI,iBAAiB,GAAG,SAAS,CAErD;IAED,4DAA4D;IAC5D,IAAI,mBAAmB,IAAI,oBAAoB,GAAG,SAAS,CAE1D;IAED,yEAAyE;IACzE,uBAAuB,CACnB,iBAAiB,EAAE,qBAAqB,GAAG,2BAA2B,EACtE,OAAO,EAAE,2BAA2B,GACrC,UAAU;IAQb,gFAAgF;IAChF,IAAI,mBAAmB,IAAI,mBAAmB,GAAG,SAAS,CAEzD;IAED;;;;OAIG;IACH,kBAAkB,CAAC,QAAQ,EAAE,eAAe,GAAG,UAAU;IAKzD,oFAAoF;IACpF,IAAI,gBAAgB,IAAI,aAAa,CAAC,eAAe,CAAC,CAErD;CACJ"}

package/dist/src/extensions/cli-builder.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliBuilder = void 0;
+const cli_server_plugin_data_explorer_1 = require("@qodalis/cli-server-plugin-data-explorer");
+/**
+ * Fluent builder for configuring CLI server processors, modules, filesystem, and data explorer providers.
+ * Passed to the `configure` callback in {@link CliServerOptions}.
+ */
+class CliBuilder {
+    _registry;
+    _modules = [];
+    _fileSystemOptions;
+    _fileStorageProvider;
+    _fileSystemApiOptions = {};
+    _dataExplorerBuilder;
+    _mcpToolProviders = [];
+    constructor(registry) {
+        this._registry = registry;
+    }
+    /** Registers a single command processor. */
+    addProcessor(processor) {
+        this._registry.register(processor);
+        return this;
+    }
+    /** Registers a module and all of its command processors. */
+    addModule(module) {
+        this._modules.push(module);
+        for (const processor of module.processors) {
+            this._registry.register(processor);
+        }
+        return this;
+    }
+    /** Returns all registered modules. */
+    get modules() {
+        return this._modules;
+    }
+    /** Configures the filesystem API with path-based access control (and `maxUploadBytes`). */
+    addFileSystem(options) {
+        this._fileSystemOptions = options;
+        this._fileSystemApiOptions = { maxUploadBytes: options.maxUploadBytes };
+        return this;
+    }
+    /** Returns the underlying command registry. */
+    get registry() {
+        return this._registry;
+    }
+    /**
+     * Sets a custom file storage provider for the filesystem API. `options`
+     * configures the HTTP API (e.g. `maxUploadBytes`, default 100 MiB).
+     */
+    setFileStorageProvider(provider, options) {
+        this._fileStorageProvider = provider;
+        if (options) {
+            this._fileSystemApiOptions = { ...options };
+        }
+        return this;
+    }
+    /** Options of the filesystem HTTP API (`maxUploadBytes`). */
+    get fileSystemApiOptions() {
+        return this._fileSystemApiOptions;
+    }
+    /** Returns the configured filesystem options, if any. */
+    get fileSystemOptions() {
+        return this._fileSystemOptions;
+    }
+    /** Returns the configured file storage provider, if any. */
+    get fileStorageProvider() {
+        return this._fileStorageProvider;
+    }
+    /** Registers a data explorer provider with its configuration options. */
+    addDataExplorerProvider(providerOrFactory, options) {
+        if (!this._dataExplorerBuilder) {
+            this._dataExplorerBuilder = new cli_server_plugin_data_explorer_1.DataExplorerBuilder();
+        }
+        this._dataExplorerBuilder.addProvider(providerOrFactory, options);
+        return this;
+    }
+    /** Returns the data explorer builder, if any providers have been registered. */
+    get dataExplorerBuilder() {
+        return this._dataExplorerBuilder;
+    }
+    /**
+     * Registers an MCP tool provider (used when the server's `mcp` option is on).
+     * On a name collision built-in feature tools win, then providers in registration
+     * order, then command tools.
+     */
+    addMcpToolProvider(provider) {
+        this._mcpToolProviders.push(provider);
+        return this;
+    }
+    /** MCP tool providers registered by plugins and the host, in registration order. */
+    get mcpToolProviders() {
+        return this._mcpToolProviders;
+    }
+}
+exports.CliBuilder = CliBuilder;
+//# sourceMappingURL=cli-builder.js.map

package/dist/src/extensions/cli-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-builder.js","sourceRoot":"","sources":["../../../src/extensions/cli-builder.ts"],"names":[],"mappings":";;;AAGA,8FAA4G;AAI5G;;;GAGG;AACH,MAAa,UAAU;IACF,SAAS,CAAqB;IAC9B,QAAQ,GAAiB,EAAE,CAAC;IACrC,kBAAkB,CAAqB;IACvC,oBAAoB,CAAwB;IAC5C,qBAAqB,GAAyB,EAAE,CAAC;IACjD,oBAAoB,CAAuB;IAClC,iBAAiB,GAAsB,EAAE,CAAC;IAE3D,YAAY,QAA4B;QACpC,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;IAC9B,CAAC;IAED,4CAA4C;IAC5C,YAAY,CAAC,SAA+B;QACxC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,4DAA4D;IAC5D,SAAS,CAAC,MAAkB;QACxB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC3B,KAAK,MAAM,SAAS,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;YACxC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QACvC,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,sCAAsC;IACtC,IAAI,OAAO;QACP,OAAO,IAAI,CAAC,QAAQ,CAAC;IACzB,CAAC;IAED,2FAA2F;IAC3F,aAAa,CAAC,OAA0B;QACpC,IAAI,CAAC,kBAAkB,GAAG,OAAO,CAAC;QAClC,IAAI,CAAC,qBAAqB,GAAG,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC;QACxE,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,+CAA+C;IAC/C,IAAI,QAAQ;QACR,OAAO,IAAI,CAAC,SAAS,CAAC;IAC1B,CAAC;IAED;;;OAGG;IACH,sBAAsB,CAAC,QAA8B,EAAE,OAA8B;QACjF,IAAI,CAAC,oBAAoB,GAAG,QAAQ,CAAC;QACrC,IAAI,OAAO,EAAE,CAAC;YACV,IAAI,CAAC,qBAAqB,GAAG,EAAE,GAAG,OAAO,EAAE,CAAC;QAChD,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,6DAA6D;IAC7D,IAAI,oBAAoB;QACpB,OAAO,IAAI,CAAC,qBAAqB,CAAC;IACtC,CAAC;IAED,yDAAyD;IACzD,IAAI,iBAAiB;QACjB,OAAO,IAAI,CAAC,kBAAkB,CAAC;IACnC,CAAC;IAED,4DAA4D;IAC5D,IAAI,mBAAmB;QACnB,OAAO,IAAI,CAAC,oBAAoB,CAAC;IACrC,CAAC;IAED,yEAAyE;IACzE,uBAAuB,CACnB,iBAAsE,EACtE,OAAoC;QAEpC,IAAI,CAAC,IAAI,CAAC,oBAAoB,EAAE,CAAC;YAC7B,IAAI,CAAC,oBAAoB,GAAG,IAAI,qDAAmB,EAAE,CAAC;QAC1D,CAAC;QACD,IAAI,CAAC,oBAAoB,CAAC,WAAW,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC;QAClE,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,gFAAgF;IAChF,IAAI,mBAAmB;QACnB,OAAO,IAAI,CAAC,oBAAoB,CAAC;IACrC,CAAC;IAED;;;;OAIG;IACH,kBAAkB,CAAC,QAAyB;QACxC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,oFAAoF;IACpF,IAAI,gBAAgB;QAChB,OAAO,IAAI,CAAC,iBAAiB,CAAC;IAClC,CAAC;CACJ;AAvGD,gCAuGC"}

package/dist/src/extensions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/extensions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC"}

package/dist/src/extensions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/extensions/index.ts"],"names":[],"mappings":";;;AAAA,6CAA2C;AAAlC,yGAAA,UAAU,OAAA"}

package/dist/src/filesystem/filesystem-options.d.ts

@@ -0,0 +1,16 @@
+/** Default largest accepted upload: 100 MiB. */
+export declare const DEFAULT_MAX_UPLOAD_BYTES: number;
+/** Options of the filesystem HTTP API (`/api/qcli/fs`). */
+export interface FileSystemApiOptions {
+    /**
+     * Largest file accepted by `POST /upload`, in bytes (default 100 MiB,
+     * {@link DEFAULT_MAX_UPLOAD_BYTES}). Larger uploads are refused with `413`.
+     */
+    maxUploadBytes?: number;
+}
+/** Configuration for the filesystem API access control. */
+export interface FileSystemOptions extends FileSystemApiOptions {
+    /** Absolute paths that the filesystem API is allowed to access. */
+    allowedPaths: string[];
+}
+//# sourceMappingURL=filesystem-options.d.ts.map

package/dist/src/filesystem/filesystem-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-options.d.ts","sourceRoot":"","sources":["../../../src/filesystem/filesystem-options.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,eAAO,MAAM,wBAAwB,QAAoB,CAAC;AAE1D,2DAA2D;AAC3D,MAAM,WAAW,oBAAoB;IACjC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,2DAA2D;AAC3D,MAAM,WAAW,iBAAkB,SAAQ,oBAAoB;IAC3D,mEAAmE;IACnE,YAAY,EAAE,MAAM,EAAE,CAAC;CAC1B"}

package/dist/src/filesystem/filesystem-options.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_UPLOAD_BYTES = void 0;
+/** Default largest accepted upload: 100 MiB. */
+exports.DEFAULT_MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
+//# sourceMappingURL=filesystem-options.js.map

package/dist/src/filesystem/filesystem-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-options.js","sourceRoot":"","sources":["../../../src/filesystem/filesystem-options.ts"],"names":[],"mappings":";;;AAAA,gDAAgD;AACnC,QAAA,wBAAwB,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC"}

package/dist/src/filesystem/filesystem-path-validator.d.ts

@@ -0,0 +1,15 @@
+import { FileSystemOptions } from './filesystem-options';
+/**
+ * Validates that requested filesystem paths fall within the configured
+ * allowed directories. Blocks path-traversal attempts and resolves symlinks.
+ */
+export declare class FileSystemPathValidator {
+    private readonly allowedPaths;
+    constructor(options: FileSystemOptions);
+    /**
+     * Returns `true` when `requestedPath` resolves to a location inside one
+     * of the allowed directories.
+     */
+    isPathAllowed(requestedPath: string): boolean;
+}
+//# sourceMappingURL=filesystem-path-validator.d.ts.map

package/dist/src/filesystem/filesystem-path-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-path-validator.d.ts","sourceRoot":"","sources":["../../../src/filesystem/filesystem-path-validator.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;;GAGG;AACH,qBAAa,uBAAuB;IAChC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAW;gBAE5B,OAAO,EAAE,iBAAiB;IAItC;;;OAGG;IACH,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO;CAuBhD"}

package/dist/src/filesystem/filesystem-path-validator.js

@@ -0,0 +1,72 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileSystemPathValidator = void 0;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+/**
+ * Validates that requested filesystem paths fall within the configured
+ * allowed directories. Blocks path-traversal attempts and resolves symlinks.
+ */
+class FileSystemPathValidator {
+    allowedPaths;
+    constructor(options) {
+        this.allowedPaths = options.allowedPaths.map((p) => path.resolve(p));
+    }
+    /**
+     * Returns `true` when `requestedPath` resolves to a location inside one
+     * of the allowed directories.
+     */
+    isPathAllowed(requestedPath) {
+        const resolved = path.resolve(requestedPath);
+        // Block explicit traversal in the normalised path
+        if (resolved.includes('..')) {
+            return false;
+        }
+        // Attempt to resolve symlinks so a link outside allowed dirs is caught
+        let realPath;
+        try {
+            realPath = fs.realpathSync(resolved);
+        }
+        catch {
+            // Path does not exist yet (e.g. mkdir/upload target) — fall back
+            // to the normalised form which is safe enough for the check.
+            realPath = resolved;
+        }
+        return this.allowedPaths.some((allowed) => realPath === allowed || realPath.startsWith(allowed + path.sep));
+    }
+}
+exports.FileSystemPathValidator = FileSystemPathValidator;
+//# sourceMappingURL=filesystem-path-validator.js.map

package/dist/src/filesystem/filesystem-path-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-path-validator.js","sourceRoot":"","sources":["../../../src/filesystem/filesystem-path-validator.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,2CAA6B;AAC7B,uCAAyB;AAGzB;;;GAGG;AACH,MAAa,uBAAuB;IACf,YAAY,CAAW;IAExC,YAAY,OAA0B;QAClC,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IACzE,CAAC;IAED;;;OAGG;IACH,aAAa,CAAC,aAAqB;QAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QAE7C,kDAAkD;QAClD,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,OAAO,KAAK,CAAC;QACjB,CAAC;QAED,uEAAuE;QACvE,IAAI,QAAgB,CAAC;QACrB,IAAI,CAAC;YACD,QAAQ,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;QACzC,CAAC;QAAC,MAAM,CAAC;YACL,iEAAiE;YACjE,6DAA6D;YAC7D,QAAQ,GAAG,QAAQ,CAAC;QACxB,CAAC;QAED,OAAO,IAAI,CAAC,YAAY,CAAC,IAAI,CACzB,CAAC,OAAO,EAAE,EAAE,CACR,QAAQ,KAAK,OAAO,IAAI,QAAQ,CAAC,UAAU,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CACtE,CAAC;IACN,CAAC;CACJ;AAlCD,0DAkCC"}