@qodalis/cli-server-abstractions 1.0.0-beta.12

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Qodalis Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# @qodalis/cli-server-abstractions
+
+Shared interfaces and base classes for building [Qodalis CLI](https://qodalis.com/) command processors. **Zero framework dependencies** — install this package when writing plugins, without pulling in Express, cors, or ws.
+
+## Install
+
+```bash
+npm install @qodalis/cli-server-abstractions
+```
+
+## Quick Start
+
+Create a custom command processor by extending `CliCommandProcessor`:
+
+```typescript
+import {
+    CliCommandProcessor,
+    CliProcessCommand,
+    CliCommandParameterDescriptor,
+} from '@qodalis/cli-server-abstractions';
+
+export class GreetCommandProcessor extends CliCommandProcessor {
+    command = 'greet';
+    description = 'Greets a user by name';
+    parameters = [
+        new CliCommandParameterDescriptor('--name', 'Name to greet', true),
+    ];
+
+    async handleAsync(command: CliProcessCommand): Promise<string> {
+        const name = command.args['name'] || 'World';
+        return `Hello, ${name}!`;
+    }
+}
+```
+
+Then register the processor with the server package. See [`@qodalis/cli-server-node`](https://www.npmjs.com/package/@qodalis/cli-server-node) for server setup.
+
+## API Reference
+
+### Interfaces
+
+| Interface | Description |
+|-----------|-------------|
+| `ICliCommandProcessor` | Contract for command processors: command name, description, author, parameters, sub-processors, and `handleAsync()` |
+| `ICliCommandAuthor` | Author metadata: `name` and `email` |
+| `ICliCommandParameterDescriptor` | Parameter declaration: name, type, required flag, aliases, default value |
+| `CliProcessCommand` | Parsed command input: command name, value, args, chain commands, raw input, data payload |
+| `CliPageRequest` | The rows a list command was asked for: `skip`, `take` |
+| `CliTablePage` | The `page` of a table output: `skip`, `take`, `total?`, `hasMore`, `truncated?` |
+
+### Classes
+
+| Class | Description |
+|-------|-------------|
+| `CliCommandProcessor` | Abstract base class implementing `ICliCommandProcessor` with sensible defaults |
+| `CliCommandAuthor` | Simple implementation of `ICliCommandAuthor` |
+| `CliCommandParameterDescriptor` | Simple implementation of `ICliCommandParameterDescriptor` |
+| `CliPaging` | `--skip` / `--take` convention: `CliPaging.parameters()` and `CliPaging.from(command)` |
+
+### Constants
+
+| Constant | Description |
+|----------|-------------|
+| `DefaultLibraryAuthor` | Default `ICliCommandAuthor` instance used when no author is specified |
+| `DEFAULT_TAKE`, `MAX_TAKE` | Rows shown by default (50) and at most (500) |
+
+### `CliCommandProcessor` Members
+
+| Member | Type | Default | Description |
+|--------|------|---------|-------------|
+| `command` | `string` | *(abstract)* | The command name users type to invoke this processor |
+| `description` | `string` | *(abstract)* | Human-readable description shown in help |
+| `author` | `ICliCommandAuthor` | `DefaultLibraryAuthor` | Author metadata |
+| `version` | `string` | `'1.0.0'` | Processor version |
+| `allowUnlistedCommands` | `boolean?` | `undefined` | Accept sub-commands not in `processors` list |
+| `valueRequired` | `boolean?` | `undefined` | Whether a positional value argument is required |
+| `processors` | `ICliCommandProcessor[]?` | `undefined` | Nested sub-command processors |
+| `parameters` | `ICliCommandParameterDescriptor[]?` | `undefined` | Declared parameters for autocompletion and validation |
+| `handleAsync(command)` | method | *(abstract)* | Execute the command, return result string |
+
+## License
+
+MIT

package/dist/cli-command-author.d.ts

@@ -0,0 +1,16 @@
+/** Describes the author of a CLI command processor. */
+export interface ICliCommandAuthor {
+    /** Display name of the author. */
+    name: string;
+    /** Contact email of the author. */
+    email: string;
+}
+/** Concrete implementation of {@link ICliCommandAuthor}. */
+export declare class CliCommandAuthor implements ICliCommandAuthor {
+    name: string;
+    email: string;
+    constructor(name: string, email: string);
+}
+/** Default author used for built-in library processors. */
+export declare const DefaultLibraryAuthor: ICliCommandAuthor;
+//# sourceMappingURL=cli-command-author.d.ts.map

package/dist/cli-command-author.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-command-author.d.ts","sourceRoot":"","sources":["../src/cli-command-author.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,MAAM,WAAW,iBAAiB;IAC9B,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,4DAA4D;AAC5D,qBAAa,gBAAiB,YAAW,iBAAiB;IAE3C,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,MAAM;gBADb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM;CAE3B;AAED,2DAA2D;AAC3D,eAAO,MAAM,oBAAoB,EAAE,iBAGlC,CAAC"}

package/dist/cli-command-author.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultLibraryAuthor = exports.CliCommandAuthor = void 0;
+/** Concrete implementation of {@link ICliCommandAuthor}. */
+class CliCommandAuthor {
+    name;
+    email;
+    constructor(name, email) {
+        this.name = name;
+        this.email = email;
+    }
+}
+exports.CliCommandAuthor = CliCommandAuthor;
+/** Default author used for built-in library processors. */
+exports.DefaultLibraryAuthor = new CliCommandAuthor('Nicolae Lupei', 'nicolae.lupei@qodalis.com');
+//# sourceMappingURL=cli-command-author.js.map

package/dist/cli-command-author.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-command-author.js","sourceRoot":"","sources":["../src/cli-command-author.ts"],"names":[],"mappings":";;;AAQA,4DAA4D;AAC5D,MAAa,gBAAgB;IAEd;IACA;IAFX,YACW,IAAY,EACZ,KAAa;QADb,SAAI,GAAJ,IAAI,CAAQ;QACZ,UAAK,GAAL,KAAK,CAAQ;IACrB,CAAC;CACP;AALD,4CAKC;AAED,2DAA2D;AAC9C,QAAA,oBAAoB,GAAsB,IAAI,gBAAgB,CACvE,eAAe,EACf,2BAA2B,CAC9B,CAAC"}

package/dist/cli-command-parameter-descriptor.d.ts

@@ -0,0 +1,34 @@
+/** Describes a parameter accepted by a CLI command processor. */
+export interface ICliCommandParameterDescriptor {
+    /** Parameter name (e.g. "algorithm"). */
+    name: string;
+    /** Short alias flags (e.g. ["-a"]). */
+    aliases?: string[];
+    /** Human-readable description shown in help output. */
+    description: string;
+    /** Whether the parameter must be provided. */
+    required: boolean;
+    /** Expected value type (e.g. "string", "boolean", "number"). */
+    type: string;
+    /** Default value used when the parameter is omitted. */
+    defaultValue?: any;
+}
+/** Concrete implementation of {@link ICliCommandParameterDescriptor}. */
+export declare class CliCommandParameterDescriptor implements ICliCommandParameterDescriptor {
+    name: string;
+    description: string;
+    required: boolean;
+    type: string;
+    aliases?: string[] | undefined;
+    defaultValue?: any | undefined;
+    /**
+     * @param name - Parameter name.
+     * @param description - Human-readable description.
+     * @param required - Whether the parameter is mandatory.
+     * @param type - Expected value type.
+     * @param aliases - Short alias flags.
+     * @param defaultValue - Default value when omitted.
+     */
+    constructor(name: string, description: string, required?: boolean, type?: string, aliases?: string[] | undefined, defaultValue?: any | undefined);
+}
+//# sourceMappingURL=cli-command-parameter-descriptor.d.ts.map

package/dist/cli-command-parameter-descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-command-parameter-descriptor.d.ts","sourceRoot":"","sources":["../src/cli-command-parameter-descriptor.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,MAAM,WAAW,8BAA8B;IAC3C,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,QAAQ,EAAE,OAAO,CAAC;IAClB,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,YAAY,CAAC,EAAE,GAAG,CAAC;CACtB;AAED,yEAAyE;AACzE,qBAAa,6BAA8B,YAAW,8BAA8B;IAUrE,IAAI,EAAE,MAAM;IACZ,WAAW,EAAE,MAAM;IACnB,QAAQ,EAAE,OAAO;IACjB,IAAI,EAAE,MAAM;IACZ,OAAO,CAAC,EAAE,MAAM,EAAE;IAClB,YAAY,CAAC,EAAE,GAAG;IAd7B;;;;;;;OAOG;gBAEQ,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,QAAQ,GAAE,OAAe,EACzB,IAAI,GAAE,MAAiB,EACvB,OAAO,CAAC,EAAE,MAAM,EAAE,YAAA,EAClB,YAAY,CAAC,EAAE,GAAG,YAAA;CAEhC"}

package/dist/cli-command-parameter-descriptor.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliCommandParameterDescriptor = void 0;
+/** Concrete implementation of {@link ICliCommandParameterDescriptor}. */
+class CliCommandParameterDescriptor {
+    name;
+    description;
+    required;
+    type;
+    aliases;
+    defaultValue;
+    /**
+     * @param name - Parameter name.
+     * @param description - Human-readable description.
+     * @param required - Whether the parameter is mandatory.
+     * @param type - Expected value type.
+     * @param aliases - Short alias flags.
+     * @param defaultValue - Default value when omitted.
+     */
+    constructor(name, description, required = false, type = 'string', aliases, defaultValue) {
+        this.name = name;
+        this.description = description;
+        this.required = required;
+        this.type = type;
+        this.aliases = aliases;
+        this.defaultValue = defaultValue;
+    }
+}
+exports.CliCommandParameterDescriptor = CliCommandParameterDescriptor;
+//# sourceMappingURL=cli-command-parameter-descriptor.js.map

package/dist/cli-command-parameter-descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-command-parameter-descriptor.js","sourceRoot":"","sources":["../src/cli-command-parameter-descriptor.ts"],"names":[],"mappings":";;;AAgBA,yEAAyE;AACzE,MAAa,6BAA6B;IAU3B;IACA;IACA;IACA;IACA;IACA;IAdX;;;;;;;OAOG;IACH,YACW,IAAY,EACZ,WAAmB,EACnB,WAAoB,KAAK,EACzB,OAAe,QAAQ,EACvB,OAAkB,EAClB,YAAkB;QALlB,SAAI,GAAJ,IAAI,CAAQ;QACZ,gBAAW,GAAX,WAAW,CAAQ;QACnB,aAAQ,GAAR,QAAQ,CAAiB;QACzB,SAAI,GAAJ,IAAI,CAAmB;QACvB,YAAO,GAAP,OAAO,CAAW;QAClB,iBAAY,GAAZ,YAAY,CAAM;IAC1B,CAAC;CACP;AAjBD,sEAiBC"}

package/dist/cli-command-processor.d.ts

@@ -0,0 +1,67 @@
+import { ICliCommandAuthor } from './cli-command-author';
+import { ICliCommandParameterDescriptor } from './cli-command-parameter-descriptor';
+import { CliProcessCommand } from './cli-process-command';
+import { CliStructuredResponse } from './cli-structured-response';
+/** Contract for a CLI command processor that handles one command (and optionally sub-commands). */
+export interface ICliCommandProcessor {
+    /** Primary command keyword (e.g. "echo", "hash"). */
+    command: string;
+    /** Short description shown in help/listing output. */
+    description: string;
+    /** Author metadata for this processor. */
+    author: ICliCommandAuthor;
+    /** When true, sub-commands not listed in {@link processors} are forwarded to this processor. */
+    allowUnlistedCommands?: boolean;
+    /** When true, the command requires a positional value argument. */
+    valueRequired?: boolean;
+    /**
+     * When true, the command reads an optional positional value (`command.value`).
+     * Implied by {@link valueRequired}. MCP exposes it as an optional `value` argument.
+     */
+    acceptsValue?: boolean;
+    /** Semantic version of this processor. */
+    version: string;
+    /** Nested sub-command processors. */
+    processors?: ICliCommandProcessor[];
+    /** Parameter descriptors for this command. */
+    parameters?: ICliCommandParameterDescriptor[];
+    /**
+     * Permissions required to execute this command (all of them), enforced
+     * server-side when the users plugin protects the server.
+     */
+    requiredPermissions?: string[];
+    /**
+     * Executes the command and returns a plain-text result.
+     * @param command - Parsed command with arguments.
+     * @param signal - Optional AbortSignal to cancel the operation.
+     * @returns Plain-text output string.
+     */
+    handleAsync(command: CliProcessCommand, signal?: AbortSignal): Promise<string>;
+    /**
+     * Executes the command and returns a structured response with typed outputs.
+     * When implemented, takes precedence over {@link handleAsync}.
+     * @param command - Parsed command with arguments.
+     * @param signal - Optional AbortSignal to cancel the operation.
+     * @returns Structured response containing exit code and typed outputs.
+     */
+    handleStructuredAsync?(command: CliProcessCommand, signal?: AbortSignal): Promise<CliStructuredResponse>;
+}
+/**
+ * Abstract base class for CLI command processors with sensible defaults.
+ * Extend this class and implement {@link handleAsync} to create a new command.
+ */
+export declare abstract class CliCommandProcessor implements ICliCommandProcessor {
+    abstract command: string;
+    abstract description: string;
+    author: ICliCommandAuthor;
+    allowUnlistedCommands?: boolean;
+    valueRequired?: boolean;
+    acceptsValue?: boolean;
+    version: string;
+    processors?: ICliCommandProcessor[];
+    parameters?: ICliCommandParameterDescriptor[];
+    requiredPermissions?: string[];
+    abstract handleAsync(command: CliProcessCommand, signal?: AbortSignal): Promise<string>;
+    handleStructuredAsync?(command: CliProcessCommand, signal?: AbortSignal): Promise<CliStructuredResponse>;
+}
+//# sourceMappingURL=cli-command-processor.d.ts.map

package/dist/cli-command-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-command-processor.d.ts","sourceRoot":"","sources":["../src/cli-command-processor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAwB,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,8BAA8B,EAAE,MAAM,oCAAoC,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAElE,mGAAmG;AACnG,MAAM,WAAW,oBAAoB;IACjC,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,MAAM,EAAE,iBAAiB,CAAC;IAC1B,gGAAgG;IAChG,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,mEAAmE;IACnE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAC;IACpC,8CAA8C;IAC9C,UAAU,CAAC,EAAE,8BAA8B,EAAE,CAAC;IAC9C;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/E;;;;;;OAMG;IACH,qBAAqB,CAAC,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;CAC5G;AAED;;;GAGG;AACH,8BAAsB,mBAAoB,YAAW,oBAAoB;IACrE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,MAAM,EAAE,iBAAiB,CAAwB;IACjD,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,EAAE,MAAM,CAAW;IAC1B,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAC;IACpC,UAAU,CAAC,EAAE,8BAA8B,EAAE,CAAC;IAC9C,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE/B,QAAQ,CAAC,WAAW,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IACvF,qBAAqB,CAAC,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAC3G"}

package/dist/cli-command-processor.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliCommandProcessor = void 0;
+const cli_command_author_1 = require("./cli-command-author");
+/**
+ * Abstract base class for CLI command processors with sensible defaults.
+ * Extend this class and implement {@link handleAsync} to create a new command.
+ */
+class CliCommandProcessor {
+    author = cli_command_author_1.DefaultLibraryAuthor;
+    allowUnlistedCommands;
+    valueRequired;
+    acceptsValue;
+    version = '1.0.0';
+    processors;
+    parameters;
+    requiredPermissions;
+}
+exports.CliCommandProcessor = CliCommandProcessor;
+//# sourceMappingURL=cli-command-processor.js.map

package/dist/cli-command-processor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-command-processor.js","sourceRoot":"","sources":["../src/cli-command-processor.ts"],"names":[],"mappings":";;;AAAA,6DAA+E;AAkD/E;;;GAGG;AACH,MAAsB,mBAAmB;IAGrC,MAAM,GAAsB,yCAAoB,CAAC;IACjD,qBAAqB,CAAW;IAChC,aAAa,CAAW;IACxB,YAAY,CAAW;IACvB,OAAO,GAAW,OAAO,CAAC;IAC1B,UAAU,CAA0B;IACpC,UAAU,CAAoC;IAC9C,mBAAmB,CAAY;CAIlC;AAdD,kDAcC"}

package/dist/cli-module.d.ts

@@ -0,0 +1,28 @@
+import { ICliCommandProcessor } from './cli-command-processor';
+import { ICliCommandAuthor } from './cli-command-author';
+/**
+ * Represents a module that bundles one or more command processors.
+ */
+export interface ICliModule {
+    /** Unique name of the module. */
+    name: string;
+    /** Module version. */
+    version: string;
+    /** Short description of the module. */
+    description: string;
+    /** Author of the module. */
+    author: ICliCommandAuthor;
+    /** Command processors provided by this module. */
+    processors: ICliCommandProcessor[];
+}
+/**
+ * Base class for CLI modules providing sensible defaults.
+ */
+export declare abstract class CliModule implements ICliModule {
+    abstract name: string;
+    abstract version: string;
+    abstract description: string;
+    author: ICliCommandAuthor;
+    abstract processors: ICliCommandProcessor[];
+}
+//# sourceMappingURL=cli-module.d.ts.map

package/dist/cli-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-module.d.ts","sourceRoot":"","sources":["../src/cli-module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAwB,MAAM,sBAAsB,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,UAAU;IACvB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IAEb,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;IAEhB,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IAEpB,4BAA4B;IAC5B,MAAM,EAAE,iBAAiB,CAAC;IAE1B,kDAAkD;IAClD,UAAU,EAAE,oBAAoB,EAAE,CAAC;CACtC;AAED;;GAEG;AACH,8BAAsB,SAAU,YAAW,UAAU;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,MAAM,EAAE,iBAAiB,CAAwB;IACjD,QAAQ,CAAC,UAAU,EAAE,oBAAoB,EAAE,CAAC;CAC/C"}

package/dist/cli-module.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliModule = void 0;
+const cli_command_author_1 = require("./cli-command-author");
+/**
+ * Base class for CLI modules providing sensible defaults.
+ */
+class CliModule {
+    author = cli_command_author_1.DefaultLibraryAuthor;
+}
+exports.CliModule = CliModule;
+//# sourceMappingURL=cli-module.js.map

package/dist/cli-module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-module.js","sourceRoot":"","sources":["../src/cli-module.ts"],"names":[],"mappings":";;;AACA,6DAA+E;AAsB/E;;GAEG;AACH,MAAsB,SAAS;IAI3B,MAAM,GAAsB,yCAAoB,CAAC;CAEpD;AAND,8BAMC"}

package/dist/cli-paging.d.ts

@@ -0,0 +1,35 @@
+import { CliProcessCommand } from './cli-process-command';
+import { ICliCommandParameterDescriptor } from './cli-command-parameter-descriptor';
+/** Rows to show when the command line does not say (`--take`). */
+export declare const DEFAULT_TAKE = 50;
+/** The largest `--take` accepted; larger values are lowered to it. */
+export declare const MAX_TAKE = 500;
+/**
+ * The rows a list command was asked for, read from `--skip` and `--take`. Commands
+ * that can return many rows declare {@link CliPaging.parameters}, read the request
+ * with {@link CliPaging.from}, query with `skip` and `take`, and write the rows with
+ * `writePagedTable` so the terminal shows which rows these are and how to get the next ones.
+ */
+export interface CliPageRequest {
+    /** Rows to skip before the first one shown (0 = from the start). */
+    skip: number;
+    /** Rows to show (1 to {@link MAX_TAKE}). */
+    take: number;
+}
+/** The `--skip` / `--take` convention shared by list commands. */
+export declare class CliPaging {
+    private constructor();
+    /**
+     * The `--skip` and `--take` parameters, to add to a command's `parameters`
+     * so help and completion show them.
+     */
+    static parameters(defaultTake?: number): ICliCommandParameterDescriptor[];
+    /**
+     * The rows asked for by `command`: `--skip` (default 0; negative values become 0) and
+     * `--take` (default `defaultTake`, at most {@link MAX_TAKE}; 0, negative or invalid values
+     * fall back to the default). Values may be numbers or strings; non-integers fall back to
+     * the defaults.
+     */
+    static from(command: CliProcessCommand, defaultTake?: number): CliPageRequest;
+}
+//# sourceMappingURL=cli-paging.d.ts.map

package/dist/cli-paging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-paging.d.ts","sourceRoot":"","sources":["../src/cli-paging.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAiC,8BAA8B,EAAE,MAAM,oCAAoC,CAAC;AAEnH,kEAAkE;AAClE,eAAO,MAAM,YAAY,KAAK,CAAC;AAE/B,sEAAsE;AACtE,eAAO,MAAM,QAAQ,MAAM,CAAC;AAE5B;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC3B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,kEAAkE;AAClE,qBAAa,SAAS;IAClB,OAAO;IAEP;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,WAAW,GAAE,MAAqB,GAAG,8BAA8B,EAAE;IAcvF;;;;;OAKG;IACH,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,iBAAiB,EAAE,WAAW,GAAE,MAAqB,GAAG,cAAc;CAM9F"}

package/dist/cli-paging.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliPaging = exports.MAX_TAKE = exports.DEFAULT_TAKE = void 0;
+const cli_command_parameter_descriptor_1 = require("./cli-command-parameter-descriptor");
+/** Rows to show when the command line does not say (`--take`). */
+exports.DEFAULT_TAKE = 50;
+/** The largest `--take` accepted; larger values are lowered to it. */
+exports.MAX_TAKE = 500;
+/** The `--skip` / `--take` convention shared by list commands. */
+class CliPaging {
+    constructor() { }
+    /**
+     * The `--skip` and `--take` parameters, to add to a command's `parameters`
+     * so help and completion show them.
+     */
+    static parameters(defaultTake = exports.DEFAULT_TAKE) {
+        return [
+            new cli_command_parameter_descriptor_1.CliCommandParameterDescriptor('skip', 'Rows to skip', false, 'number', undefined, 0),
+            new cli_command_parameter_descriptor_1.CliCommandParameterDescriptor('take', `Rows to show (at most ${exports.MAX_TAKE})`, false, 'number', undefined, defaultTake),
+        ];
+    }
+    /**
+     * The rows asked for by `command`: `--skip` (default 0; negative values become 0) and
+     * `--take` (default `defaultTake`, at most {@link MAX_TAKE}; 0, negative or invalid values
+     * fall back to the default). Values may be numbers or strings; non-integers fall back to
+     * the defaults.
+     */
+    static from(command, defaultTake = exports.DEFAULT_TAKE) {
+        const skip = Math.max(readInteger(command, 'skip') ?? 0, 0);
+        const requested = readInteger(command, 'take');
+        const take = Math.min(requested !== undefined && requested > 0 ? requested : defaultTake, exports.MAX_TAKE);
+        return { skip, take };
+    }
+}
+exports.CliPaging = CliPaging;
+function readInteger(command, name) {
+    const value = command?.args?.[name];
+    let number;
+    if (typeof value === 'number') {
+        number = value;
+    }
+    else if (typeof value === 'string' && /^\s*[+-]?\d+\s*$/.test(value)) {
+        number = Number(value.trim());
+    }
+    return number !== undefined && Number.isSafeInteger(number) ? number : undefined;
+}
+//# sourceMappingURL=cli-paging.js.map

package/dist/cli-paging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-paging.js","sourceRoot":"","sources":["../src/cli-paging.ts"],"names":[],"mappings":";;;AACA,yFAAmH;AAEnH,kEAAkE;AACrD,QAAA,YAAY,GAAG,EAAE,CAAC;AAE/B,sEAAsE;AACzD,QAAA,QAAQ,GAAG,GAAG,CAAC;AAe5B,kEAAkE;AAClE,MAAa,SAAS;IAClB,gBAAuB,CAAC;IAExB;;;OAGG;IACH,MAAM,CAAC,UAAU,CAAC,cAAsB,oBAAY;QAChD,OAAO;YACH,IAAI,gEAA6B,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC;YACxF,IAAI,gEAA6B,CAC7B,MAAM,EACN,yBAAyB,gBAAQ,GAAG,EACpC,KAAK,EACL,QAAQ,EACR,SAAS,EACT,WAAW,CACd;SACJ,CAAC;IACN,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,IAAI,CAAC,OAA0B,EAAE,cAAsB,oBAAY;QACtE,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QAC5D,MAAM,SAAS,GAAG,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,EAAE,gBAAQ,CAAC,CAAC;QACpG,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAC1B,CAAC;CACJ;AAjCD,8BAiCC;AAED,SAAS,WAAW,CAAC,OAA0B,EAAE,IAAY;IACzD,MAAM,KAAK,GAAG,OAAO,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,MAA0B,CAAC;IAC/B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,GAAG,KAAK,CAAC;IACnB,CAAC;SAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrE,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AACrF,CAAC"}

package/dist/cli-process-command.d.ts

@@ -0,0 +1,23 @@
+/** Parsed representation of a CLI command submitted for execution. */
+export interface CliProcessCommand {
+    /** Primary command keyword (e.g. "hash", "http"). */
+    command: string;
+    /** Optional payload data attached to the command. */
+    data?: any;
+    /** Sub-command chain following the primary command (e.g. ["encode"] for "base64 encode"). */
+    chainCommands: string[];
+    /** Original unparsed command string as entered by the user. */
+    rawCommand: string;
+    /** Positional value argument (the first non-flag token after the command). */
+    value?: string;
+    /**
+     * The positional arguments after the command and sub-command words, split
+     * like a shell: quotes removed, backslash escapes applied, flags excluded.
+     * Sent by newer browsers; `value` stays as typed. Read it with `getPositionals`,
+     * which falls back to splitting `value` when it is missing.
+     */
+    positionals?: string[];
+    /** Named arguments parsed from flags (e.g. { algorithm: "sha256" }). */
+    args: Record<string, any>;
+}
+//# sourceMappingURL=cli-process-command.d.ts.map

package/dist/cli-process-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-process-command.d.ts","sourceRoot":"","sources":["../src/cli-process-command.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,MAAM,WAAW,iBAAiB;IAC9B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,6FAA6F;IAC7F,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC7B"}

package/dist/cli-process-command.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=cli-process-command.js.map

package/dist/cli-process-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-process-command.js","sourceRoot":"","sources":["../src/cli-process-command.ts"],"names":[],"mappings":""}

package/dist/cli-processor-filter.d.ts

@@ -0,0 +1,14 @@
+import { ICliCommandProcessor } from './cli-command-processor';
+/**
+ * Provides a mechanism to filter whether a command processor is allowed to execute.
+ * Implementations can use this to disable processors at runtime (e.g., when a plugin is toggled off).
+ */
+export interface ICliProcessorFilter {
+    /**
+     * Determines whether the given command processor is allowed to execute.
+     * @param processor - The command processor to check.
+     * @returns `true` if the processor is allowed; `false` if it should be blocked.
+     */
+    isAllowed(processor: ICliCommandProcessor): boolean;
+}
+//# sourceMappingURL=cli-processor-filter.d.ts.map

package/dist/cli-processor-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-processor-filter.d.ts","sourceRoot":"","sources":["../src/cli-processor-filter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAE/D;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAChC;;;;OAIG;IACH,SAAS,CAAC,SAAS,EAAE,oBAAoB,GAAG,OAAO,CAAC;CACvD"}

package/dist/cli-processor-filter.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=cli-processor-filter.js.map

package/dist/cli-processor-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-processor-filter.js","sourceRoot":"","sources":["../src/cli-processor-filter.ts"],"names":[],"mappings":""}

package/dist/cli-stream-command-processor.d.ts

@@ -0,0 +1,27 @@
+import { CliProcessCommand } from './cli-process-command';
+import { CliStructuredOutput } from './cli-structured-response';
+/**
+ * Optional interface for command processors that support streaming output.
+ * Processors implementing this interface can emit output chunks incrementally
+ * via the `emit` callback, enabling real-time rendering on the client.
+ *
+ * A processor can implement both ICliCommandProcessor and ICliStreamCommandProcessor.
+ * The stream execution endpoint will prefer this interface when available.
+ */
+export interface ICliStreamCommandProcessor {
+    /** Must match the command keyword of the corresponding ICliCommandProcessor. */
+    readonly command: string;
+    /**
+     * Execute the command, emitting output chunks as they become available.
+     * @param command - Parsed command with arguments.
+     * @param emit - Callback to send a single output chunk to the client.
+     * @param signal - Optional AbortSignal to cancel the operation.
+     * @returns Exit code (0 for success).
+     */
+    handleStreamAsync(command: CliProcessCommand, emit: (output: CliStructuredOutput) => void, signal?: AbortSignal): Promise<number>;
+}
+/**
+ * Type guard to check if a processor supports streaming.
+ */
+export declare function isStreamCapable(processor: unknown): processor is ICliStreamCommandProcessor;
+//# sourceMappingURL=cli-stream-command-processor.d.ts.map

package/dist/cli-stream-command-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-stream-command-processor.d.ts","sourceRoot":"","sources":["../src/cli-stream-command-processor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAEhE;;;;;;;GAOG;AACH,MAAM,WAAW,0BAA0B;IACvC,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;;;;OAMG;IACH,iBAAiB,CACb,OAAO,EAAE,iBAAiB,EAC1B,IAAI,EAAE,CAAC,MAAM,EAAE,mBAAmB,KAAK,IAAI,EAC3C,MAAM,CAAC,EAAE,WAAW,GACrB,OAAO,CAAC,MAAM,CAAC,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC3B,SAAS,EAAE,OAAO,GACnB,SAAS,IAAI,0BAA0B,CAOzC"}

package/dist/cli-stream-command-processor.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isStreamCapable = isStreamCapable;
+/**
+ * Type guard to check if a processor supports streaming.
+ */
+function isStreamCapable(processor) {
+    return (typeof processor === 'object' &&
+        processor !== null &&
+        'handleStreamAsync' in processor &&
+        typeof processor.handleStreamAsync === 'function');
+}
+//# sourceMappingURL=cli-stream-command-processor.js.map

package/dist/cli-stream-command-processor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-stream-command-processor.js","sourceRoot":"","sources":["../src/cli-stream-command-processor.ts"],"names":[],"mappings":";;AAgCA,0CASC;AAZD;;GAEG;AACH,SAAgB,eAAe,CAC3B,SAAkB;IAElB,OAAO,CACH,OAAO,SAAS,KAAK,QAAQ;QAC7B,SAAS,KAAK,IAAI;QAClB,mBAAmB,IAAI,SAAS;QAChC,OAAQ,SAAiB,CAAC,iBAAiB,KAAK,UAAU,CAC7D,CAAC;AACN,CAAC"}

package/dist/cli-structured-response.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Which rows of a longer result a table output holds:
+ * `{ "skip": 50, "take": 50, "total": 120, "hasMore": true }`.
+ * `total` and `truncated` are omitted when not set.
+ */
+export interface CliTablePage {
+    /** Rows skipped before the first row of the table. */
+    skip: number;
+    /** Rows asked for (the table may hold fewer). */
+    take: number;
+    /** All rows of the result, when the command knows it. */
+    total?: number;
+    /** Whether more rows follow (`--skip` = skip + rows shown). */
+    hasMore: boolean;
+    /**
+     * Set when the server cut an unpaged table (the `maxTableRows` server option):
+     * the command does not page, so `--skip` will not show the rest.
+     */
+    truncated?: boolean;
+}
+/** A single typed output block within a structured CLI response. */
+export type CliStructuredOutput = {
+    type: 'text';
+    value: string;
+    style?: 'success' | 'error' | 'info' | 'warning';
+} | {
+    type: 'table';
+    headers: string[];
+    rows: string[][];
+    /**
+     * Which rows of a longer result these are, when the command pages (`--skip`, `--take`);
+     * the terminal shows it under the table with the command for the next rows.
+     */
+    page?: CliTablePage;
+} | {
+    type: 'list';
+    items: string[];
+    ordered?: boolean;
+} | {
+    type: 'json';
+    value: any;
+} | {
+    type: 'key-value';
+    entries: {
+        key: string;
+        value: string;
+    }[];
+};
+/** Response envelope returned by structured command execution, containing an exit code and typed outputs. */
+export interface CliStructuredResponse {
+    /** Process exit code (0 for success, non-zero for errors). */
+    exitCode: number;
+    /** Ordered list of typed output blocks. */
+    outputs: CliStructuredOutput[];
+}
+//# sourceMappingURL=cli-structured-response.d.ts.map