@decaf-ts/cli 0.3.5 → 0.3.7

package/LICENSE.md

@@ -1,157 +1,22 @@
-# GNU LESSER GENERAL PUBLIC LICENSE
+MIT License
 
-Version 3, 29 June 2007
+Copyright (c) 2025 Tiago Venceslau and Contributors
 
-Copyright (C) 2025 Tiago Venceslau
-<https:/github.com/TiagoVenceslau>
+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:
 
-Everyone is permitted to copy and distribute verbatim copies of this
-license document, but changing it is not allowed.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-This version of the GNU Lesser General Public License incorporates the
-terms and conditions of version 3 of the GNU General Public License,
-supplemented by the additional permissions listed below.
+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.
 
-## 0. Additional Definitions.
-
-As used herein, "this License" refers to version 3 of the GNU Lesser
-General Public License, and the "GNU GPL" refers to version 3 of the
-GNU General Public License.
-
-"The Library" refers to a covered work governed by this License, other
-than an Application or a Combined Work as defined below.
-
-An "Application" is any work that makes use of an interface provided
-by the Library, but which is not otherwise based on the Library.
-Defining a subclass of a class defined by the Library is deemed a mode
-of using an interface provided by the Library.
-
-A "Combined Work" is a work produced by combining or linking an
-Application with the Library. The particular version of the Library
-with which the Combined Work was made is also called the "Linked
-Version".
-
-The "Minimal Corresponding Source" for a Combined Work means the
-Corresponding Source for the Combined Work, excluding any source code
-for portions of the Combined Work that, considered in isolation, are
-based on the Application, and not on the Linked Version.
-
-The "Corresponding Application Code" for a Combined Work means the
-object code and/or source code for the Application, including any data
-and utility programs needed for reproducing the Combined Work from the
-Application, but excluding the System Libraries of the Combined Work.
-
-## 1. Exception to Section 3 of the GNU GPL.
-
-You may convey a covered work under sections 3 and 4 of this License
-without being bound by section 3 of the GNU GPL.
-
-## 2. Conveying Modified Versions.
-
-If you modify a copy of the Library, and, in your modifications, a
-facility refers to a function or data to be supplied by an Application
-that uses the facility (other than as an argument passed when the
-facility is invoked), then you may convey a copy of the modified
-version:
-
--   a) under this License, provided that you make a good faith effort
-    to ensure that, in the event an Application does not supply the
-    function or data, the facility still operates, and performs
-    whatever part of its purpose remains meaningful, or
--   b) under the GNU GPL, with none of the additional permissions of
-    this License applicable to that copy.
-
-## 3. Object Code Incorporating Material from Library Header Files.
-
-The object code form of an Application may incorporate material from a
-header file that is part of the Library. You may convey such object
-code under terms of your choice, provided that, if the incorporated
-material is not limited to numerical parameters, data structure
-layouts and accessors, or small macros, inline functions and templates
-(ten or fewer lines in length), you do both of the following:
-
--   a) Give prominent notice with each copy of the object code that
-    the Library is used in it and that the Library and its use are
-    covered by this License.
--   b) Accompany the object code with a copy of the GNU GPL and this
-    license document.
-
-## 4. Combined Works.
-
-You may convey a Combined Work under terms of your choice that, taken
-together, effectively do not restrict modification of the portions of
-the Library contained in the Combined Work and reverse engineering for
-debugging such modifications, if you also do each of the following:
-
--   a) Give prominent notice with each copy of the Combined Work that
-    the Library is used in it and that the Library and its use are
-    covered by this License.
--   b) Accompany the Combined Work with a copy of the GNU GPL and this
-    license document.
--   c) For a Combined Work that displays copyright notices during
-    execution, include the copyright notice for the Library among
-    these notices, as well as a reference directing the user to the
-    copies of the GNU GPL and this license document.
--   d) Do one of the following:
-    -   0) Convey the Minimal Corresponding Source under the terms of
-           this License, and the Corresponding Application Code in a form
-           suitable for, and under terms that permit, the user to
-           recombine or relink the Application with a modified version of
-           the Linked Version to produce a modified Combined Work, in the
-           manner specified by section 6 of the GNU GPL for conveying
-           Corresponding Source.
-    -   1) Use a suitable shared library mechanism for linking with
-           the Library. A suitable mechanism is one that (a) uses at run
-           time a copy of the Library already present on the user's
-           computer system, and (b) will operate properly with a modified
-           version of the Library that is interface-compatible with the
-           Linked Version.
--   e) Provide Installation Information, but only if you would
-    otherwise be required to provide such information under section 6
-    of the GNU GPL, and only to the extent that such information is
-    necessary to install and execute a modified version of the
-    Combined Work produced by recombining or relinking the Application
-    with a modified version of the Linked Version. (If you use option
-    4d0, the Installation Information must accompany the Minimal
-    Corresponding Source and Corresponding Application Code. If you
-    use option 4d1, you must provide the Installation Information in
-    the manner specified by section 6 of the GNU GPL for conveying
-    Corresponding Source.)
-
-## 5. Combined Libraries.
-
-You may place library facilities that are a work based on the Library
-side by side in a single library together with other library
-facilities that are not Applications and are not covered by this
-License, and convey such a combined library under terms of your
-choice, if you do both of the following:
-
--   a) Accompany the combined library with a copy of the same work
-    based on the Library, uncombined with any other library
-    facilities, conveyed under the terms of this License.
--   b) Give prominent notice with the combined library that part of it
-    is a work based on the Library, and explaining where to find the
-    accompanying uncombined form of the same work.
-
-## 6. Revised Versions of the GNU Lesser General Public License.
-
-The Free Software Foundation may publish revised and/or new versions
-of the GNU Lesser General Public License from time to time. Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns.
-
-Each version is given a distinguishing version number. If the Library
-as you received it specifies that a certain numbered version of the
-GNU Lesser General Public License "or any later version" applies to
-it, you have the option of following the terms and conditions either
-of that published version or of any later version published by the
-Free Software Foundation. If the Library as you received it does not
-specify a version number of the GNU Lesser General Public License, you
-may choose any version of the GNU Lesser General Public License ever
-published by the Free Software Foundation.
-
-If the Library as you received it specifies that a proxy can decide
-whether future versions of the GNU Lesser General Public License shall
-apply, that proxy's public statement of acceptance of any version is
-permanent authorization for you to choose that version for the
-Library.

package/README.md

@@ -1,8 +1,9 @@
 ![Banner](./workdocs/assets/Banner.png)
 
-## Decaf-ts cli
+## Decaf-ts CLI
+
+A modular command-line interface framework for Decaf-ts that dynamically discovers and loads CLI modules from different packages. The CLI provides a unified entry point (`decaf`) for executing commands from various Decaf modules, making it easy to extend with new functionality without modifying the core CLI code.
 
-Exposes global cli tool that consumes other modules' clis under a standard command `decaf`
 
 ![Licence](https://img.shields.io/github/license/decaf-ts/cli.svg?style=plastic)
 ![GitHub language count](https://img.shields.io/github/languages/count/decaf-ts/cli?style=plastic)
@@ -35,14 +36,168 @@ Documentation available [here](https://decaf-ts.github.io/cli/)
 
 ### Description
 
+The Decaf-ts CLI is a powerful and extensible command-line interface framework designed to provide a unified entry point for all Decaf-ts modules. It enables developers to create modular CLI commands that can be discovered and executed through a single command-line tool.
+
+#### Core Components
+
+1. **CliWrapper**: The central class that manages the discovery, loading, and execution of CLI modules. It:
+   - Crawls the filesystem to find CLI module files
+   - Dynamically loads modules using JavaScript's import system
+   - Registers commands with Commander.js
+   - Provides a simple API for running commands
+
+2. **CLIUtils**: A utility class that provides helper methods for:
+   - Loading modules from files
+   - Normalizing imports between ESM and CommonJS formats
+   - Retrieving package information (name, version)
+   - Initializing Commander.js commands
+
+3. **CLI Module System**: A standardized way for Decaf-ts packages to expose CLI functionality:
+   - Modules are discovered by filename (cli-module.js)
+   - Each module exports a function that returns a Commander.js Command object
+   - Modules can define their own subcommands and options
+
+#### Key Features
+
+- **Dynamic Discovery**: Automatically finds CLI modules in the project and its dependencies
+- **Modular Architecture**: Each module can define its own commands independently
+- **Extensible**: New commands can be added without modifying the core CLI code
+- **Unified Interface**: All commands are accessible through the single `decaf` command
+- **Self-documenting**: Leverages Commander.js to provide help text and usage information
+
+#### Technical Details
+
+The CLI uses a recursive filesystem crawler to find modules up to a configurable depth. It handles both ESM and CommonJS module formats, making it compatible with various JavaScript environments. The command structure follows the pattern:
+
+```
+decaf <module> <command> [options]
+```
+
+Where `<module>` is the name of a Decaf-ts module and `<command>` is a specific command provided by that module.
 
 
 ### How to Use
 
-- [Initial Setup](../../workdocs/tutorials/For%20Developers.md#_initial-setup_)
-- [Installation](../../workdocs/tutorials/For%20Developers.md#installation)
+- [Initial Setup](./workdocs/tutorials/For%20Developers.md#_initial-setup_)
+- [Installation](./workdocs/tutorials/For%20Developers.md#installation)
+
+#### Using the CLI
+
+The Decaf-ts CLI provides a unified command-line interface for all Decaf-ts modules. Here are some examples of how to use it:
+
+```bash
+# Get general help
+npx decaf help
+
+# List all available modules
+npx decaf list
+
+# Get help for a specific module
+npx decaf help <module-name>
+
+# Run a command from a specific module
+npx decaf <module-name> <command> [options]
+```
+
+#### Creating a CLI Module
+
+To create a CLI module for your Decaf-ts package, follow these steps:
+
+1. Create a file named `cli-module.ts` in your package:
+
+```typescript
+import { Command } from "commander";
+
+export default function myModule(): Command {
+  return new Command()
+    .command("hello <name>")
+    .description("Say hello to someone")
+    .action((name: string) => {
+      console.log(`Hello, ${name}!`);
+    });
+}
+```
+
+2. Configure your TypeScript build to output the CLI module:
+
+```json
+// tsconfig.cli.json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist/cli"
+  },
+  "include": ["src/cli-module.ts"]
+}
+```
+
+3. Add a build step to your package.json:
+
+```json
+"scripts": {
+  "build:cli": "tsc --project tsconfig.cli.json"
+}
+```
+
+#### Using the CliWrapper Programmatically
+
+You can also use the CliWrapper class programmatically in your own code:
+
+```typescript
+import { CliWrapper } from "@decaf-ts/cli";
+
+// Create a new CLI wrapper with custom options
+const cli = new CliWrapper("./src", 2);
+
+// Run the CLI with custom arguments
+cli.run(process.argv)
+  .then(() => {
+    console.log("CLI commands executed successfully");
+  })
+  .catch((error) => {
+    console.error("Error executing CLI commands:", error);
+  });
+```
+
+#### Using CLIUtils
+
+The CLIUtils class provides utility methods for working with CLI modules:
+
+```typescript
+import { CLIUtils } from "@decaf-ts/cli";
+import { Command } from "commander";
+
+// Initialize a Command object with package information
+const command = new Command();
+CLIUtils.initialize(command, "./path/to/package");
+
+// Get package information
+const version = CLIUtils.packageVersion("./path/to/package");
+const name = CLIUtils.packageName("./path/to/package");
 
+// Load a CLI module from a file
+const modulePath = "./path/to/cli-module.js";
+CLIUtils.loadFromFile(modulePath)
+  .then((module) => {
+    const command = module();
+    console.log("Loaded command:", command.name());
+  })
+  .catch((error) => {
+    console.error("Error loading module:", error);
+  });
+```
+
+#### Demo CLI Module
 
+The CLI package includes a demo module that shows how to create a simple command:
+
+```typescript
+// Run the demo command
+npx decaf demo command "hello world"
+
+// Output:
+// executed demo command with type variable: hello world
+```
 
 
 ### Related